@taskforcehq/taskforce 0.3.303 → 0.3.305

package/dist/hooks/sync/orchestratorShared.test.js

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { readPersistedSyncWatermarks, savePersistedSyncWatermarks, WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX, } from './orchestratorShared';
+describe('orchestratorShared sync watermarks', () => {
+    const workspaceId = 'workspace-local-active';
+    beforeEach(() => {
+        localStorage.clear();
+    });
+    it('keeps persisted sync watermarks available across long idle periods', () => {
+        const key = `${WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX}.${workspaceId}`;
+        localStorage.setItem(key, JSON.stringify({
+            v: 8,
+            savedAt: '2026-04-14T10:00:00.000Z',
+            taskWatermarks: [['task-1', '2026-04-14T09:00:00.000Z']],
+            initiativeWatermarks: [['initiative-1', '2026-04-14T09:00:00.000Z']],
+            workstreamWatermarks: [],
+            documentWatermarks: [],
+            assetWatermarks: [],
+            documentReviewSessionWatermarks: [],
+            documentReviewCommentWatermarks: [],
+            annotatedAttachmentSessionWatermarks: [],
+            taskEventWatermarks: [['event-1', '2026-04-14T09:30:00.000Z']],
+            taxonomyStateFingerprint: ''
+        }));
+        const persisted = readPersistedSyncWatermarks(workspaceId, '');
+        expect(persisted).not.toBeNull();
+        expect(persisted?.taskWatermarks.get('task-1')).toBe('2026-04-14T09:00:00.000Z');
+        expect(persisted?.initiativeWatermarks.get('initiative-1')).toBe('2026-04-14T09:00:00.000Z');
+        expect(persisted?.taskEventWatermarks.get('event-1')).toBe('2026-04-14T09:30:00.000Z');
+    });
+    it('still clears task watermarks when the taxonomy fingerprint changes', () => {
+        savePersistedSyncWatermarks(workspaceId, {
+            taskWatermarks: new Map([['task-1', '2026-04-14T09:00:00.000Z']]),
+            initiativeWatermarks: new Map([['initiative-1', '2026-04-14T09:00:00.000Z']]),
+            workstreamWatermarks: new Map(),
+            documentWatermarks: new Map(),
+            assetWatermarks: new Map(),
+            documentReviewSessionWatermarks: new Map(),
+            documentReviewCommentWatermarks: new Map(),
+            annotatedAttachmentSessionWatermarks: new Map(),
+            taskEventWatermarks: new Map([['event-1', '2026-04-14T09:30:00.000Z']]),
+            taxonomyStateFingerprint: 'fingerprint-a'
+        });
+        const persisted = readPersistedSyncWatermarks(workspaceId, 'fingerprint-b');
+        expect(persisted).not.toBeNull();
+        expect(persisted?.taskWatermarks.size).toBe(0);
+        expect(persisted?.initiativeWatermarks.get('initiative-1')).toBe('2026-04-14T09:00:00.000Z');
+        expect(persisted?.taskEventWatermarks.get('event-1')).toBe('2026-04-14T09:30:00.000Z');
+    });
+});

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

@@ -0,0 +1,25 @@
+import type { MutableRefObject } from 'react';
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+import type { RealtimeSyncSignal } from '../useRealtimeSync';
+interface CreateRealtimeSyncBridgeArgs {
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    workspaceCloudSyncEnabled: boolean;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    workspacePullInFlightRef: MutableRefObject<boolean>;
+    realtimePullDebounceRef: MutableRefObject<number | null>;
+    realtimeSuppressedEventIdsRef: MutableRefObject<Set<string>>;
+    clearWorkspaceRetry: () => void;
+    isWorkspaceRetryPending: () => boolean;
+    pullWorkspaceChangesFromCloud: () => Promise<boolean>;
+}
+export declare function createRealtimeSyncBridge({ cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, workspaceSyncPhase, workspacePullInFlightRef, realtimePullDebounceRef, realtimeSuppressedEventIdsRef, clearWorkspaceRetry, isWorkspaceRetryPending, pullWorkspaceChangesFromCloud }: CreateRealtimeSyncBridgeArgs): {
+    handleRealtimeSignal: (signal: RealtimeSyncSignal) => void;
+    recordSuppressedEventIds: (eventIds: Iterable<string>, options?: {
+        queueRef?: MutableRefObject<string[]>;
+        maxQueueSize?: number;
+        ttlMs?: number;
+    }) => void;
+    clearRealtimePullDebounce: () => void;
+};
+export {};

package/dist/hooks/sync/realtime.js

@@ -0,0 +1,60 @@
+export function createRealtimeSyncBridge({ cloudAuthConfigured, runtimeMode, workspaceCloudSyncEnabled, workspaceSyncPhase, workspacePullInFlightRef, realtimePullDebounceRef, realtimeSuppressedEventIdsRef, clearWorkspaceRetry, isWorkspaceRetryPending, pullWorkspaceChangesFromCloud }) {
+    const handleRealtimeSignal = (signal) => {
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return;
+        if (workspaceSyncPhase === 'provision-local')
+            return;
+        const eventId = String(signal?.eventId || '').trim();
+        if (eventId && realtimeSuppressedEventIdsRef.current.delete(eventId))
+            return;
+        if (workspacePullInFlightRef.current)
+            return;
+        if (isWorkspaceRetryPending()) {
+            clearWorkspaceRetry();
+        }
+        if (realtimePullDebounceRef.current !== null) {
+            window.clearTimeout(realtimePullDebounceRef.current);
+        }
+        realtimePullDebounceRef.current = window.setTimeout(() => {
+            realtimePullDebounceRef.current = null;
+            void pullWorkspaceChangesFromCloud();
+        }, 180);
+    };
+    const recordSuppressedEventIds = (eventIds, options) => {
+        const queueRef = options?.queueRef;
+        const maxQueueSize = Number.isFinite(options?.maxQueueSize) ? Math.max(1, Number(options?.maxQueueSize)) : 2048;
+        const ttlMs = Number.isFinite(options?.ttlMs) ? Math.max(0, Number(options?.ttlMs)) : null;
+        for (const rawEventId of eventIds) {
+            const eventId = String(rawEventId || '').trim();
+            if (!eventId || realtimeSuppressedEventIdsRef.current.has(eventId))
+                continue;
+            realtimeSuppressedEventIdsRef.current.add(eventId);
+            if (queueRef) {
+                queueRef.current.push(eventId);
+            }
+            if (ttlMs !== null) {
+                window.setTimeout(() => {
+                    realtimeSuppressedEventIdsRef.current.delete(eventId);
+                }, ttlMs);
+            }
+        }
+        if (queueRef) {
+            while (queueRef.current.length > maxQueueSize) {
+                const stale = queueRef.current.shift();
+                if (stale)
+                    realtimeSuppressedEventIdsRef.current.delete(stale);
+            }
+        }
+    };
+    const clearRealtimePullDebounce = () => {
+        if (realtimePullDebounceRef.current !== null) {
+            window.clearTimeout(realtimePullDebounceRef.current);
+            realtimePullDebounceRef.current = null;
+        }
+    };
+    return {
+        handleRealtimeSignal,
+        recordSuppressedEventIds,
+        clearRealtimePullDebounce
+    };
+}

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

@@ -0,0 +1,69 @@
+import type { MutableRefObject } from 'react';
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+interface CreateSyncRecoveryCoordinatorArgs {
+    currentWorkspaceId: string;
+    taxonomyStateFingerprint: string;
+    workspaceCloudSyncEnabled: boolean;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    workspaceLastPullAt: string | null;
+    lastBootstrapPhaseRef: MutableRefObject<WorkspaceSyncPhase>;
+    workspaceRepairModeRef: MutableRefObject<boolean>;
+    workspaceForceFullAiProfilePushRef: MutableRefObject<boolean>;
+    workspaceStartupRepairRanRef: MutableRefObject<boolean>;
+    workspaceStartupFullReconcileRanRef: MutableRefObject<boolean>;
+    workspaceFullReconcileInFlightRef: MutableRefObject<boolean>;
+    workspacePullCursorRef: MutableRefObject<string | null>;
+    workspaceAttachBootstrapBaselineSignatureRef: MutableRefObject<string>;
+    workspaceCaptureAttachBootstrapBaselineRef: MutableRefObject<boolean>;
+    workspacePendingSignatureRef: MutableRefObject<string>;
+    workspaceLastPushedSignatureRef: MutableRefObject<string>;
+    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>>;
+    bootstrapPhaseStartedAtRef: MutableRefObject<number | null>;
+    bootstrapLastProgressAtRef: MutableRefObject<number | null>;
+    acquireWorkspaceSyncLease: (workspaceId: string, owner: 'pull' | 'push' | 'repair') => Promise<boolean>;
+    releaseWorkspaceSyncLease: (workspaceId: string) => void;
+    forceClearWorkspaceSyncLease: (workspaceId: string) => void;
+    clearWorkspaceRetry: () => void;
+    clearWorkspaceIssue: () => void;
+    reportWorkspaceWindowContention: (operation: 'pull' | 'push' | 'repair') => void;
+    persistWorkspaceSyncPatch: (patch: {
+        phase: WorkspaceSyncPhase;
+        pullCursor: null;
+        lastErrorMessage: null;
+    }) => Promise<unknown>;
+    buildWorkspaceSyncSignature: () => string;
+    pullWorkspaceChangesFromCloud: (options?: {
+        repairMode?: boolean;
+        forceCursorNull?: boolean;
+    }) => Promise<boolean>;
+    pushWorkspaceChangesToCloud: (signature: string, options?: {
+        forceAllAiProfiles?: boolean;
+        repairMode?: boolean;
+    }) => Promise<boolean>;
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    isAuthenticated: boolean;
+    checkAuthSession: () => Promise<boolean>;
+}
+export declare function createSyncRecoveryCoordinator({ currentWorkspaceId, taxonomyStateFingerprint, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceLastPullAt, lastBootstrapPhaseRef, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspaceStartupRepairRanRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, workspacePullCursorRef, workspaceAttachBootstrapBaselineSignatureRef, workspaceCaptureAttachBootstrapBaselineRef, workspacePendingSignatureRef, workspaceLastPushedSignatureRef, workspaceLastPushedWatermarksRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease, clearWorkspaceRetry, clearWorkspaceIssue, reportWorkspaceWindowContention, persistWorkspaceSyncPatch, buildWorkspaceSyncSignature, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, cloudAuthConfigured, runtimeMode, isAuthenticated, checkAuthSession }: CreateSyncRecoveryCoordinatorArgs): {
+    retryWorkspaceCloudSync: () => Promise<boolean>;
+    resetWorkspaceSyncCursorAndPull: () => Promise<void>;
+};
+export {};

package/dist/hooks/sync/recovery.js

@@ -0,0 +1,118 @@
+import { resolveRepairPhase } from './bootstrap';
+import { savePersistedSyncWatermarks } from './orchestratorShared';
+export function createSyncRecoveryCoordinator({ currentWorkspaceId, taxonomyStateFingerprint, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceLastPullAt, lastBootstrapPhaseRef, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspaceStartupRepairRanRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, workspacePullCursorRef, workspaceAttachBootstrapBaselineSignatureRef, workspaceCaptureAttachBootstrapBaselineRef, workspacePendingSignatureRef, workspaceLastPushedSignatureRef, workspaceLastPushedWatermarksRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease, clearWorkspaceRetry, clearWorkspaceIssue, reportWorkspaceWindowContention, persistWorkspaceSyncPatch, buildWorkspaceSyncSignature, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, cloudAuthConfigured, runtimeMode, isAuthenticated, checkAuthSession }) {
+    const retryWorkspaceCloudSync = async () => {
+        clearWorkspaceRetry();
+        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
+            return false;
+        if (!isAuthenticated) {
+            const authed = await checkAuthSession();
+            if (!authed)
+                return false;
+        }
+        workspaceForceFullAiProfilePushRef.current = true;
+        if (workspaceSyncPhase === 'provision-local') {
+            const signature = buildWorkspaceSyncSignature();
+            if (!signature)
+                return false;
+            return pushWorkspaceChangesToCloud(signature, { forceAllAiProfiles: true });
+        }
+        const pulled = await pullWorkspaceChangesFromCloud();
+        if (workspaceSyncPhase === 'attach-cloud')
+            return pulled;
+        const signature = buildWorkspaceSyncSignature();
+        if (signature) {
+            workspacePendingSignatureRef.current = signature;
+            const pushed = await pushWorkspaceChangesToCloud(signature, {
+                forceAllAiProfiles: workspaceForceFullAiProfilePushRef.current === true
+            });
+            return pulled || pushed;
+        }
+        return pulled;
+    };
+    const resetWorkspaceSyncCursorAndPull = async () => {
+        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'repair');
+        if (!leaseAcquired) {
+            forceClearWorkspaceSyncLease(currentWorkspaceId);
+            const reclaimed = await acquireWorkspaceSyncLease(currentWorkspaceId, 'repair');
+            if (!reclaimed) {
+                reportWorkspaceWindowContention('repair');
+                return;
+            }
+        }
+        clearWorkspaceRetry();
+        clearWorkspaceIssue();
+        bootstrapPhaseStartedAtRef.current = null;
+        bootstrapLastProgressAtRef.current = null;
+        workspacePullCursorRef.current = null;
+        workspaceAttachBootstrapBaselineSignatureRef.current = '';
+        workspaceCaptureAttachBootstrapBaselineRef.current = false;
+        workspacePendingSignatureRef.current = '';
+        workspaceLastPushedSignatureRef.current = '';
+        workspaceLastPushedWatermarksRef.current = new Map();
+        workspaceLastPushedInitiativeIdsRef.current = new Set();
+        workspaceLastPushedInitiativeWatermarksRef.current = new Map();
+        workspaceLastPushedWorkstreamIdsRef.current = new Set();
+        workspaceLastPushedWorkstreamWatermarksRef.current = new Map();
+        workspaceLastPushedAiProfileIdsRef.current = new Set();
+        workspaceLastPushedAiProfileWatermarksRef.current = new Map();
+        workspaceLastPushedDocumentPathsRef.current = new Set();
+        workspaceLastPushedDocumentWatermarksRef.current = new Map();
+        workspaceLastPushedAssetPathsRef.current = new Set();
+        workspaceLastPushedAssetWatermarksRef.current = new Map();
+        workspaceLastPushedDocumentReviewSessionIdsRef.current = new Set();
+        workspaceLastPushedDocumentReviewSessionWatermarksRef.current = new Map();
+        workspaceLastPushedDocumentReviewCommentIdsRef.current = new Set();
+        workspaceLastPushedDocumentReviewCommentWatermarksRef.current = new Map();
+        workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set();
+        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map();
+        workspaceLastPushedTaskEventWatermarksRef.current = new Map();
+        workspaceForceFullAiProfilePushRef.current = false;
+        workspaceStartupRepairRanRef.current = false;
+        workspaceStartupFullReconcileRanRef.current = false;
+        workspaceFullReconcileInFlightRef.current = false;
+        savePersistedSyncWatermarks(currentWorkspaceId, {
+            taskWatermarks: new Map(),
+            initiativeWatermarks: new Map(),
+            workstreamWatermarks: new Map(),
+            documentWatermarks: new Map(),
+            assetWatermarks: new Map(),
+            documentReviewSessionWatermarks: new Map(),
+            documentReviewCommentWatermarks: new Map(),
+            annotatedAttachmentSessionWatermarks: new Map(),
+            taskEventWatermarks: new Map(),
+            taxonomyStateFingerprint
+        });
+        try {
+            if (!workspaceCloudSyncEnabled)
+                return;
+            workspaceRepairModeRef.current = true;
+            const repairPhase = resolveRepairPhase({
+                workspaceSyncPhase,
+                lastBootstrapPhase: lastBootstrapPhaseRef.current,
+                workspaceLastPullAt
+            });
+            await persistWorkspaceSyncPatch({
+                phase: repairPhase,
+                pullCursor: null,
+                lastErrorMessage: null
+            });
+            if (repairPhase === 'provision-local') {
+                const signature = buildWorkspaceSyncSignature();
+                if (!signature)
+                    return;
+                await pushWorkspaceChangesToCloud(signature, { forceAllAiProfiles: true, repairMode: true });
+                return;
+            }
+            await pullWorkspaceChangesFromCloud({ repairMode: true });
+        }
+        finally {
+            workspaceRepairModeRef.current = false;
+            releaseWorkspaceSyncLease(currentWorkspaceId);
+        }
+    };
+    return {
+        retryWorkspaceCloudSync,
+        resetWorkspaceSyncCursorAndPull
+    };
+}

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

@@ -0,0 +1,123 @@
+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>>;
+    workspaceDeletedTaskWatermarksRef: MutableRefObject<Map<string, 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, workspaceDeletedTaskWatermarksRef, workspacePullCursorRef, workspaceLastPushedWatermarksRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, workspaceCaptureAttachBootstrapBaselineRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, bootstrapLastProgressAtRef, realtimeSuppressedEventQueueRef, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceSyncPendingChanges, setTasks, setArchivedTasks }: CreateWorkspaceTransferCoordinatorArgs): {
+    pushWorkspaceChangesToCloud: (signature: string, options?: {
+        forceAllAiProfiles?: boolean;
+        repairMode?: boolean;
+    }) => Promise<boolean>;
+    pullWorkspaceChangesFromCloud: (options?: {
+        repairMode?: boolean;
+        forceCursorNull?: boolean;
+    }) => Promise<boolean>;
+};
+export {};