@taskforcehq/taskforce 0.3.170 → 0.3.301

package/dist/hooks/useWorkspaceSyncController.js

@@ -1,75 +1,101 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { calculateWorkspaceRetryDelayMs } from '../sync/syncService';
-import { bootstrapPushWorkspaceSnapshot } from '../sync/cloudSyncApi';
-const WORKSPACE_PULL_LEASE_KEY_PREFIX = 'taskforce.sync.pullLease.v1';
-const WORKSPACE_PULL_COOLDOWN_KEY_PREFIX = 'taskforce.sync.pullCooldown.v1';
-const WORKSPACE_PULL_LEASE_MS = 30_000;
-const WORKSPACE_PULL_MIN_INTERVAL_MS = 10_000;
-const SYNC_DEBUG_LOG_KEY = 'taskforce.syncDebug.v1';
-function isSyncDebugLoggingEnabled() {
-    if (typeof window === 'undefined')
-        return false;
+import { normalizeWorkspaceSyncStateCompat } from '../compat/workspaceSyncCompat';
+import { createDefaultWorkspaceSyncState } from '../sync/workspaceSyncState';
+const WORKSPACE_SYNC_LEASE_KEY_PREFIX = 'taskforce.sync.lease.v1';
+const WORKSPACE_SYNC_LEASE_CHANNEL = 'taskforce.sync.lease.v1';
+const WORKSPACE_SYNC_LEASE_HEARTBEAT_MS = 2500;
+const WORKSPACE_SYNC_LEASE_TTL_MS = 9000;
+function isValidWorkspaceKey(workspaceId) {
+    const workspaceKey = String(workspaceId || '').trim();
+    return workspaceKey.length > 0 && workspaceKey.toLowerCase() !== 'default';
+}
+function normalizeCursor(value) {
+    const normalized = String(value || '').trim();
+    return normalized.length > 0 ? normalized : null;
+}
+function getWorkspaceSyncLeaseKey(workspaceId) {
+    return `${WORKSPACE_SYNC_LEASE_KEY_PREFIX}.${workspaceId}`;
+}
+function parseWorkspaceSyncLeaseRecord(raw) {
+    if (!raw)
+        return null;
     try {
-        const raw = String(window.localStorage.getItem(SYNC_DEBUG_LOG_KEY) || '').trim().toLowerCase();
-        return raw === '1' || raw === 'true' || raw === 'on' || raw === 'yes';
+        const parsed = JSON.parse(raw);
+        const ownerId = String(parsed?.ownerId || '').trim();
+        const workspaceId = String(parsed?.workspaceId || '').trim();
+        const operation = String(parsed?.operation || '').trim();
+        const heartbeatAt = String(parsed?.heartbeatAt || '').trim();
+        const expiresAt = String(parsed?.expiresAt || '').trim();
+        if (!ownerId || !workspaceId || !heartbeatAt || !expiresAt)
+            return null;
+        if (operation !== 'pull' && operation !== 'push' && operation !== 'repair')
+            return null;
+        return { ownerId, workspaceId, operation, heartbeatAt, expiresAt };
     }
     catch {
-        return false;
+        return null;
     }
 }
-function logSyncDebug(event, details) {
-    if (!isSyncDebugLoggingEnabled())
-        return;
-    const payload = details && typeof details === 'object' ? details : {};
-    console.info('[Taskforce Sync]', event, payload);
-}
-function getWorkspacePullLeaseStorageKey(workspaceId) {
-    return `${WORKSPACE_PULL_LEASE_KEY_PREFIX}.${workspaceId}`;
+function createWorkspaceSyncLeaseRecord(ownerId, workspaceId, operation, nowMs) {
+    return {
+        ownerId,
+        workspaceId,
+        operation,
+        heartbeatAt: new Date(nowMs).toISOString(),
+        expiresAt: new Date(nowMs + WORKSPACE_SYNC_LEASE_TTL_MS).toISOString()
+    };
 }
-function getWorkspacePullCooldownStorageKey(workspaceId) {
-    return `${WORKSPACE_PULL_COOLDOWN_KEY_PREFIX}.${workspaceId}`;
+function isLeaseExpired(record, nowMs = Date.now()) {
+    if (!record)
+        return true;
+    const expiresAtMs = Date.parse(record.expiresAt);
+    return !Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs;
 }
-function isValidWorkspaceKey(workspaceId) {
-    const workspaceKey = String(workspaceId || '').trim();
-    return workspaceKey.length > 0 && workspaceKey.toLowerCase() !== 'default';
+function buildWorkspaceSyncStatePatch(current, patch) {
+    const next = {
+        ...current,
+        ...patch,
+        version: 2,
+        phase: patch.phase || current.phase,
+        pullCursor: patch.pullCursor === undefined ? current.pullCursor : normalizeCursor(patch.pullCursor),
+        lastPullAt: patch.lastPullAt === undefined ? current.lastPullAt : normalizeCursor(patch.lastPullAt),
+        lastPushAt: patch.lastPushAt === undefined ? current.lastPushAt : normalizeCursor(patch.lastPushAt),
+        lastSyncedAt: patch.lastSyncedAt === undefined ? current.lastSyncedAt : normalizeCursor(patch.lastSyncedAt),
+        lastErrorMessage: patch.lastErrorMessage === undefined ? current.lastErrorMessage : (patch.lastErrorMessage ?? null)
+    };
+    if (!next.enabled) {
+        next.phase = 'idle';
+        next.pullCursor = null;
+    }
+    return next;
 }
 export function useWorkspaceSyncController(input) {
-    const { currentWorkspaceId, setWorkspaceSyncReady, setWorkspaceCloudHydrated, setWorkspaceCloudSyncEnabled, setWorkspaceSyncSourceOfTruth, setWorkspaceSyncOnboardingCompleted, setUserGlobalLastSyncedAt, setWorkspaceLastPullAt, setWorkspaceLastPushAt } = input;
+    const { currentWorkspaceId, setWorkspaceCloudSyncEnabled, setWorkspaceSyncPhase, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceLastErrorMessage } = input;
     const [workspaceRetryAt, setWorkspaceRetryAt] = useState(null);
-    const [workspaceBootstrapSyncInProgress, setWorkspaceBootstrapSyncInProgress] = useState(false);
-    const [workspaceBootstrapSyncPages, setWorkspaceBootstrapSyncPages] = useState(0);
-    const [workspaceBootstrapSyncAppliedChanges, setWorkspaceBootstrapSyncAppliedChanges] = useState(0);
-    const [workspaceSyncFailureCount, setWorkspaceSyncFailureCount] = useState(0);
-    const [workspaceSyncRetryScheduledCount, setWorkspaceSyncRetryScheduledCount] = useState(0);
-    const [workspaceSyncAuthFailureCount, setWorkspaceSyncAuthFailureCount] = useState(0);
-    const [workspaceSyncLastFailureSource, setWorkspaceSyncLastFailureSource] = useState(null);
-    const [workspaceSyncLastFailureStatusCode, setWorkspaceSyncLastFailureStatusCode] = useState(null);
-    const workspacePushInFlightRef = useRef(false);
-    const workspacePullInFlightRef = useRef(false);
     const workspaceRetryTimerRef = useRef(null);
     const workspaceRetryAtMsRef = useRef(null);
     const workspaceRetryAttemptRef = useRef(0);
+    // Current product support is one active syncing local window per workspace.
+    // These refs guard same-window reentry, while the lease helpers below
+    // coordinate sync ownership across local windows on the same machine.
+    const workspacePushInFlightRef = useRef(false);
+    const workspacePullInFlightRef = useRef(false);
     const workspaceLastPushedSignatureRef = useRef('');
     const workspacePendingSignatureRef = useRef('');
     const workspaceLastPushedTaskIdsRef = useRef(new Set());
     const workspaceDeletedTaskIdsRef = useRef(new Set());
     const workspacePullCursorRef = useRef(null);
-    const workspacePullBootstrapDoneRef = useRef(false);
-    const workspaceBackfillForcedRef = useRef(new Set());
-    const workspaceSyncReadyRef = useRef(new Set());
-    const workspaceCloudHydratedRef = useRef(new Set());
-    const workspaceSyncStateReadCountRef = useRef(0);
-    const workspacePullLeaseOwnerRef = useRef('');
-    const activeLockWorkspaceIdRef = useRef(null);
-    const activeLockAbortControllerRef = useRef(null);
-    const onFailureRecordedRef = useRef(input.onFailureRecorded);
-    useEffect(() => {
-        onFailureRecordedRef.current = input.onFailureRecorded;
-    }, [input.onFailureRecorded]);
-    if (!workspacePullLeaseOwnerRef.current) {
+    const workspaceSyncStateRef = useRef(createDefaultWorkspaceSyncState());
+    const workspaceSyncLeaseOwnerIdRef = useRef('');
+    const workspaceSyncLeaseWorkspaceRef = useRef(null);
+    const workspaceSyncLeaseOperationRef = useRef(null);
+    const workspaceSyncLeaseHeartbeatTimerRef = useRef(null);
+    const workspaceSyncLeaseChannelRef = useRef(null);
+    if (!workspaceSyncLeaseOwnerIdRef.current) {
         const now = Date.now().toString(36);
         const rand = Math.random().toString(36).slice(2, 10);
-        workspacePullLeaseOwnerRef.current = `pull-${now}-${rand}`;
+        workspaceSyncLeaseOwnerIdRef.current = `sync-lease-${now}-${rand}`;
     }
     const clearWorkspaceRetry = useCallback(() => {
         workspaceRetryAttemptRef.current = 0;
@@ -80,35 +106,19 @@ export function useWorkspaceSyncController(input) {
         }
         setWorkspaceRetryAt(null);
     }, []);
-    const scheduleWorkspacePullRetry = useCallback((invokePull, options) => {
+    const scheduleWorkspaceRetry = useCallback((invokeSync, options) => {
         if (typeof window === 'undefined')
             return;
-        setWorkspaceSyncRetryScheduledCount((prev) => prev + 1);
-        const attempt = workspaceRetryAttemptRef.current + 1;
-        workspaceRetryAttemptRef.current = attempt;
-        const computedDelayMs = calculateWorkspaceRetryDelayMs(attempt);
+        const nextAttempt = Math.max(1, workspaceRetryAttemptRef.current + 1);
+        workspaceRetryAttemptRef.current = nextAttempt;
+        const computedDelayMs = calculateWorkspaceRetryDelayMs(nextAttempt);
         const explicitDelayMs = Number(options?.minDelayMs);
         const delayMs = Number.isFinite(explicitDelayMs) && explicitDelayMs > 0
             ? Math.max(computedDelayMs, Math.floor(explicitDelayMs))
             : computedDelayMs;
         const retryAtMs = Date.now() + delayMs;
-        const retryAtIso = new Date(Date.now() + delayMs).toISOString();
-        const workspaceKey = String(options?.workspaceId || '').trim();
-        if (workspaceKey) {
-            try {
-                const cooldownKey = getWorkspacePullCooldownStorageKey(workspaceKey);
-                const raw = window.localStorage.getItem(cooldownKey);
-                const parsed = raw ? JSON.parse(raw) : null;
-                const existingNextAt = Number(parsed?.nextAllowedAt || 0);
-                const nextAllowedAt = Math.max(existingNextAt, retryAtMs);
-                window.localStorage.setItem(cooldownKey, JSON.stringify({ nextAllowedAt }));
-            }
-            catch {
-                // best-effort only
-            }
-        }
         workspaceRetryAtMsRef.current = retryAtMs;
-        setWorkspaceRetryAt(retryAtIso);
+        setWorkspaceRetryAt(new Date(retryAtMs).toISOString());
         if (workspaceRetryTimerRef.current !== null) {
             window.clearTimeout(workspaceRetryTimerRef.current);
         }
@@ -116,461 +126,276 @@ export function useWorkspaceSyncController(input) {
             workspaceRetryTimerRef.current = null;
             workspaceRetryAtMsRef.current = null;
             setWorkspaceRetryAt(null);
-            if (workspaceKey) {
-                try {
-                    const cooldownKey = getWorkspacePullCooldownStorageKey(workspaceKey);
-                    const raw = window.localStorage.getItem(cooldownKey);
-                    const parsed = raw ? JSON.parse(raw) : null;
-                    const nextAllowedAt = Number(parsed?.nextAllowedAt || 0);
-                    if (Number.isFinite(nextAllowedAt) && nextAllowedAt <= retryAtMs) {
-                        window.localStorage.setItem(cooldownKey, JSON.stringify({ nextAllowedAt: Date.now() - 1 }));
-                    }
-                }
-                catch {
-                    // best-effort only
-                }
-            }
-            void invokePull();
+            void invokeSync();
         }, delayMs);
     }, []);
-    const isWorkspacePullRetryPending = useCallback(() => {
+    const isWorkspaceRetryPending = useCallback(() => {
         const retryAtMs = workspaceRetryAtMsRef.current;
         return typeof retryAtMs === 'number' && Number.isFinite(retryAtMs) && retryAtMs > Date.now();
     }, []);
-    const isWorkspacePullCooldownActive = useCallback((workspaceId) => {
+    const readWorkspaceSyncLease = useCallback((workspaceId) => {
         if (typeof window === 'undefined')
-            return false;
+            return null;
         const workspaceKey = String(workspaceId || '').trim();
-        if (!workspaceKey)
-            return false;
-        try {
-            const raw = window.localStorage.getItem(getWorkspacePullCooldownStorageKey(workspaceKey));
-            const parsed = raw ? JSON.parse(raw) : null;
-            const nextAllowedAt = Number(parsed?.nextAllowedAt || 0);
-            return Number.isFinite(nextAllowedAt) && nextAllowedAt > Date.now();
-        }
-        catch {
-            return false;
-        }
+        if (!isValidWorkspaceKey(workspaceKey))
+            return null;
+        return parseWorkspaceSyncLeaseRecord(window.localStorage.getItem(getWorkspaceSyncLeaseKey(workspaceKey)));
     }, []);
-    const markWorkspacePullCooldown = useCallback((workspaceId, minDelayMs) => {
-        if (typeof window === 'undefined')
-            return;
+    const broadcastWorkspaceSyncLeaseUpdate = useCallback((workspaceId) => {
         const workspaceKey = String(workspaceId || '').trim();
         if (!workspaceKey)
             return;
         try {
-            const cooldownKey = getWorkspacePullCooldownStorageKey(workspaceKey);
-            const raw = window.localStorage.getItem(cooldownKey);
-            const parsed = raw ? JSON.parse(raw) : null;
-            const existingNextAt = Number(parsed?.nextAllowedAt || 0);
-            const explicitDelayMs = Number(minDelayMs);
-            const baselineDelay = Number.isFinite(explicitDelayMs) && explicitDelayMs > 0
-                ? Math.max(WORKSPACE_PULL_MIN_INTERVAL_MS, Math.floor(explicitDelayMs))
-                : WORKSPACE_PULL_MIN_INTERVAL_MS;
-            const nextAllowedAt = Math.max(existingNextAt, Date.now() + baselineDelay);
-            window.localStorage.setItem(cooldownKey, JSON.stringify({ nextAllowedAt }));
+            workspaceSyncLeaseChannelRef.current?.postMessage({ workspaceId: workspaceKey });
         }
         catch {
             // best-effort only
         }
     }, []);
-    const tryAcquireWorkspacePullLease = useCallback(async (workspaceId) => {
+    const writeWorkspaceSyncLease = useCallback((workspaceId, operation) => {
+        if (typeof window === 'undefined')
+            return null;
         const workspaceKey = String(workspaceId || '').trim();
-        if (!workspaceKey)
-            return true;
-        const fallbackAcquire = () => {
-            if (typeof window === 'undefined')
-                return true;
-            try {
-                const leaseKey = getWorkspacePullLeaseStorageKey(workspaceKey);
-                const ownerId = workspacePullLeaseOwnerRef.current;
-                const now = Date.now();
-                const raw = window.localStorage.getItem(leaseKey);
-                const parsed = raw ? JSON.parse(raw) : null;
-                const existingOwner = typeof parsed?.owner === 'string' ? parsed.owner : '';
-                const existingExpiresAt = Number(parsed?.expiresAt || 0);
-                const leaseActive = Number.isFinite(existingExpiresAt) && existingExpiresAt > now;
-                if (leaseActive && existingOwner && existingOwner !== ownerId)
-                    return false;
-                const nextLease = {
-                    owner: ownerId,
-                    acquiredAt: now,
-                    expiresAt: now + WORKSPACE_PULL_LEASE_MS
-                };
-                window.localStorage.setItem(leaseKey, JSON.stringify(nextLease));
-                const verifyRaw = window.localStorage.getItem(leaseKey);
-                const verify = verifyRaw ? JSON.parse(verifyRaw) : null;
-                return verify?.owner === ownerId;
-            }
-            catch {
-                return true;
-            }
-        };
-        if (typeof window === 'undefined' || typeof navigator === 'undefined' || !navigator.locks) {
-            return fallbackAcquire();
-        }
-        if (activeLockAbortControllerRef.current) {
-            return activeLockWorkspaceIdRef.current === workspaceKey; // Already holding the lock for this workspace
-        }
-        const lockName = `taskforce.sync.pullLock.${workspaceKey}`;
-        const controller = new AbortController();
+        if (!isValidWorkspaceKey(workspaceKey))
+            return null;
+        const record = createWorkspaceSyncLeaseRecord(workspaceSyncLeaseOwnerIdRef.current, workspaceKey, operation, Date.now());
         try {
-            const acquired = await new Promise((resolve) => {
-                navigator.locks.request(lockName, { mode: 'exclusive', ifAvailable: true, signal: controller.signal }, async (lock) => {
-                    if (!lock) {
-                        resolve(false);
-                        return;
-                    }
-                    activeLockAbortControllerRef.current = controller;
-                    activeLockWorkspaceIdRef.current = workspaceKey;
-                    resolve(true);
-                    // Hold the lock indefinitely until aborted
-                    return new Promise(() => { });
-                }).catch(() => {
-                    resolve(false);
-                });
-            });
-            return acquired;
+            window.localStorage.setItem(getWorkspaceSyncLeaseKey(workspaceKey), JSON.stringify(record));
         }
         catch {
-            return fallbackAcquire();
+            return null;
+        }
+        broadcastWorkspaceSyncLeaseUpdate(workspaceKey);
+        return record;
+    }, [broadcastWorkspaceSyncLeaseUpdate]);
+    const stopWorkspaceSyncLeaseHeartbeat = useCallback(() => {
+        if (workspaceSyncLeaseHeartbeatTimerRef.current !== null && typeof window !== 'undefined') {
+            window.clearInterval(workspaceSyncLeaseHeartbeatTimerRef.current);
+            workspaceSyncLeaseHeartbeatTimerRef.current = null;
         }
     }, []);
-    const releaseWorkspacePullLease = useCallback((workspaceId) => {
-        const workspaceKey = String(workspaceId || '').trim();
-        if (workspaceKey
-            && activeLockWorkspaceIdRef.current
-            && activeLockWorkspaceIdRef.current !== workspaceKey) {
+    const releaseWorkspaceSyncLease = useCallback((workspaceId, options) => {
+        if (typeof window === 'undefined')
             return;
-        }
-        if (activeLockAbortControllerRef.current) {
-            activeLockAbortControllerRef.current.abort();
-            activeLockAbortControllerRef.current = null;
-        }
-        activeLockWorkspaceIdRef.current = null;
-        if (!workspaceKey || typeof window === 'undefined')
+        const workspaceKey = String(workspaceId || workspaceSyncLeaseWorkspaceRef.current || '').trim();
+        if (!workspaceKey)
             return;
+        const current = readWorkspaceSyncLease(workspaceKey);
+        const ownedByThisWindow = current?.ownerId === workspaceSyncLeaseOwnerIdRef.current;
+        if (!options?.force && current && !ownedByThisWindow)
+            return;
+        stopWorkspaceSyncLeaseHeartbeat();
         try {
-            const leaseKey = getWorkspacePullLeaseStorageKey(workspaceKey);
-            const raw = window.localStorage.getItem(leaseKey);
-            const parsed = raw ? JSON.parse(raw) : null;
-            if (parsed?.owner === workspacePullLeaseOwnerRef.current) {
-                window.localStorage.removeItem(leaseKey);
-            }
+            window.localStorage.removeItem(getWorkspaceSyncLeaseKey(workspaceKey));
         }
         catch {
             // best-effort only
         }
-    }, []);
-    const recordWorkspaceSyncFailure = useCallback((source, statusCode) => {
-        const normalizedStatusCode = typeof statusCode === 'number' && Number.isFinite(statusCode) ? statusCode : null;
-        setWorkspaceSyncFailureCount((prev) => prev + 1);
-        setWorkspaceSyncLastFailureSource(source);
-        setWorkspaceSyncLastFailureStatusCode(normalizedStatusCode);
-        const onFailureRecorded = onFailureRecordedRef.current;
-        if (onFailureRecorded)
-            onFailureRecorded(source, normalizedStatusCode);
-    }, []);
-    const incrementWorkspaceSyncAuthFailure = useCallback(() => {
-        setWorkspaceSyncAuthFailureCount((prev) => prev + 1);
-    }, []);
-    const persistWorkspaceSyncPatch = useCallback(async (patch) => {
-        if (!isValidWorkspaceKey(currentWorkspaceId))
+        workspaceSyncLeaseWorkspaceRef.current = null;
+        workspaceSyncLeaseOperationRef.current = null;
+        broadcastWorkspaceSyncLeaseUpdate(workspaceKey);
+    }, [broadcastWorkspaceSyncLeaseUpdate, readWorkspaceSyncLease, stopWorkspaceSyncLeaseHeartbeat]);
+    const startWorkspaceSyncLeaseHeartbeat = useCallback((workspaceId, operation) => {
+        if (typeof window === 'undefined')
             return;
-        try {
-            await fetch('/api/taskforce/ui-state', {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                credentials: 'include',
-                body: JSON.stringify({
-                    workspaceId: currentWorkspaceId,
-                    stateKey: 'workspace-sync',
-                    patch: {
-                        ...patch,
-                        updatedAt: new Date().toISOString()
-                    }
-                })
-            });
+        stopWorkspaceSyncLeaseHeartbeat();
+        workspaceSyncLeaseHeartbeatTimerRef.current = window.setInterval(() => {
+            const workspaceKey = String(workspaceSyncLeaseWorkspaceRef.current || '').trim();
+            const activeOperation = workspaceSyncLeaseOperationRef.current;
+            if (!workspaceKey || !activeOperation) {
+                stopWorkspaceSyncLeaseHeartbeat();
+                return;
+            }
+            const current = readWorkspaceSyncLease(workspaceKey);
+            if (current?.ownerId !== workspaceSyncLeaseOwnerIdRef.current) {
+                stopWorkspaceSyncLeaseHeartbeat();
+                workspaceSyncLeaseWorkspaceRef.current = null;
+                workspaceSyncLeaseOperationRef.current = null;
+                return;
+            }
+            void writeWorkspaceSyncLease(workspaceKey, activeOperation);
+        }, WORKSPACE_SYNC_LEASE_HEARTBEAT_MS);
+        workspaceSyncLeaseWorkspaceRef.current = workspaceId;
+        workspaceSyncLeaseOperationRef.current = operation;
+    }, [readWorkspaceSyncLease, stopWorkspaceSyncLeaseHeartbeat, writeWorkspaceSyncLease]);
+    const acquireWorkspaceSyncLease = useCallback(async (workspaceId, operation) => {
+        if (typeof window === 'undefined')
+            return true;
+        const workspaceKey = String(workspaceId || '').trim();
+        if (!isValidWorkspaceKey(workspaceKey))
+            return false;
+        const current = readWorkspaceSyncLease(workspaceKey);
+        const ownedByThisWindow = current?.ownerId === workspaceSyncLeaseOwnerIdRef.current;
+        if (ownedByThisWindow) {
+            const refreshed = writeWorkspaceSyncLease(workspaceKey, operation);
+            if (!refreshed)
+                return false;
+            startWorkspaceSyncLeaseHeartbeat(workspaceKey, operation);
+            return true;
         }
-        catch {
-            // ignore persistence errors
+        if (current && !isLeaseExpired(current)) {
+            return false;
+        }
+        const written = writeWorkspaceSyncLease(workspaceKey, operation);
+        if (!written)
+            return false;
+        const confirmed = readWorkspaceSyncLease(workspaceKey);
+        if (!confirmed || confirmed.ownerId !== workspaceSyncLeaseOwnerIdRef.current) {
+            return false;
         }
-    }, [currentWorkspaceId]);
+        startWorkspaceSyncLeaseHeartbeat(workspaceKey, operation);
+        return true;
+    }, [readWorkspaceSyncLease, startWorkspaceSyncLeaseHeartbeat, writeWorkspaceSyncLease]);
+    const forceClearWorkspaceSyncLease = useCallback((workspaceId) => {
+        releaseWorkspaceSyncLease(workspaceId, { force: true });
+    }, [releaseWorkspaceSyncLease]);
+    const applyWorkspaceSyncStateSnapshot = useCallback((nextState) => {
+        const current = workspaceSyncStateRef.current;
+        const next = buildWorkspaceSyncStatePatch(current, {
+            enabled: Boolean(nextState.enabled),
+            phase: nextState.phase || current.phase,
+            pullCursor: nextState.pullCursor,
+            lastPullAt: nextState.lastPullAt,
+            lastPushAt: nextState.lastPushAt,
+            lastSyncedAt: nextState.lastSyncedAt,
+            lastErrorMessage: nextState.lastErrorMessage
+        });
+        workspaceSyncStateRef.current = next;
+        workspacePullCursorRef.current = next.pullCursor;
+        setWorkspaceCloudSyncEnabled(next.enabled);
+        setWorkspaceSyncPhase(next.phase);
+        setWorkspaceLastPullAt(next.lastPullAt);
+        setWorkspaceLastPushAt(next.lastPushAt);
+        setWorkspaceLastErrorMessage(next.lastErrorMessage ?? null);
+    }, [
+        setWorkspaceCloudSyncEnabled,
+        setWorkspaceSyncPhase,
+        setWorkspaceLastPullAt,
+        setWorkspaceLastPushAt,
+        setWorkspaceLastErrorMessage
+    ]);
+    const persistWorkspaceSyncPatch = useCallback(async (patch) => {
+        const next = buildWorkspaceSyncStatePatch(workspaceSyncStateRef.current, patch);
+        workspaceSyncStateRef.current = next;
+        workspacePullCursorRef.current = next.pullCursor;
+        const res = await fetch('/api/taskforce/ui-state', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            credentials: 'include',
+            body: JSON.stringify({
+                workspaceId: currentWorkspaceId,
+                stateKey: 'workspace-sync',
+                patch: next
+            })
+        });
+        const payload = await res.json().catch(() => ({}));
+        if (!res.ok || payload?.success === false) {
+            throw new Error(payload?.error || `Failed to persist workspace sync state (${res.status})`);
+        }
+        applyWorkspaceSyncStateSnapshot(next);
+        return next;
+    }, [applyWorkspaceSyncStateSnapshot, currentWorkspaceId]);
     const loadWorkspaceSyncState = useCallback(async () => {
-        const workspaceId = String(currentWorkspaceId || '').trim();
-        if (!isValidWorkspaceKey(workspaceId)) {
-            setWorkspaceCloudSyncEnabled(false);
-            setWorkspaceSyncSourceOfTruth(null);
-            setWorkspaceSyncOnboardingCompleted(false);
-            workspacePullCursorRef.current = null;
-            workspacePullBootstrapDoneRef.current = false;
-            logSyncDebug('workspace_sync_state_read_skipped_invalid_workspace', { workspaceId });
+        if (!isValidWorkspaceKey(currentWorkspaceId)) {
+            const initialState = createDefaultWorkspaceSyncState();
+            workspaceSyncStateRef.current = initialState;
+            applyWorkspaceSyncStateSnapshot(initialState);
             return;
         }
-        workspaceSyncStateReadCountRef.current += 1;
-        const readCount = workspaceSyncStateReadCountRef.current;
         try {
-            const res = await fetch(`/api/taskforce/ui-state?key=workspace-sync&workspaceId=${encodeURIComponent(workspaceId)}`, {
+            const res = await fetch(`/api/taskforce/ui-state?key=workspace-sync&workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
                 method: 'GET',
                 credentials: 'include'
             });
-            if (!res.ok) {
-                logSyncDebug('workspace_sync_state_read_failed', {
-                    workspaceId,
-                    readCount,
-                    status: res.status
-                });
-                if (res.status === 429) {
-                    logSyncDebug('workspace_sync_state_rate_limited', {
-                        workspaceId,
-                        readCount
-                    });
-                }
+            if (!res.ok)
                 return;
-            }
             const data = await res.json().catch(() => ({}));
-            const state = (data?.state && typeof data.state === 'object')
+            const normalized = normalizeWorkspaceSyncStateCompat(data?.state && typeof data.state === 'object'
                 ? data.state
-                : null;
-            if (!state) {
-                logSyncDebug('workspace_sync_state_read_empty', {
-                    workspaceId,
-                    readCount
-                });
-                return;
-            }
-            setWorkspaceCloudSyncEnabled(Boolean(state.cloudSyncEnabled));
-            const source = String(state.sourceOfTruth || '').trim().toLowerCase();
-            if (source === 'cloud' || source === 'local') {
-                setWorkspaceSyncSourceOfTruth(source);
-            }
-            else {
-                setWorkspaceSyncSourceOfTruth(null);
+                : null);
+            workspaceSyncStateRef.current = normalized.state;
+            applyWorkspaceSyncStateSnapshot(normalized.state);
+            if (normalized.changed) {
+                void persistWorkspaceSyncPatch(normalized.state);
             }
-            setWorkspaceSyncOnboardingCompleted(Boolean(state.onboardingCompleted));
-            const lastSyncedAt = typeof state.lastSyncedAt === 'string' ? state.lastSyncedAt : '';
-            if (lastSyncedAt.trim().length > 0) {
-                setUserGlobalLastSyncedAt(lastSyncedAt.trim());
-            }
-            const lastPullAt = typeof state.lastPullAt === 'string' ? state.lastPullAt : '';
-            if (lastPullAt.trim().length > 0) {
-                setWorkspaceLastPullAt(lastPullAt.trim());
-            }
-            const lastPushAt = typeof state.lastPushAt === 'string' ? state.lastPushAt : '';
-            if (lastPushAt.trim().length > 0) {
-                setWorkspaceLastPushAt(lastPushAt.trim());
-            }
-            const pullCursor = typeof state.pullCursor === 'string' ? state.pullCursor : '';
-            const trimmedCursor = pullCursor.trim();
-            workspacePullCursorRef.current = trimmedCursor.length > 0 ? trimmedCursor : null;
-            // Only mark bootstrap done if we actually have a valid persisted cursor.
-            // An empty cursor means the previous bootstrap was incomplete; let it re-run.
-            workspacePullBootstrapDoneRef.current = trimmedCursor.length > 0;
-            logSyncDebug('workspace_sync_state_read_ok', {
-                workspaceId,
-                readCount,
-                sourceOfTruth: source === 'cloud' || source === 'local' ? source : null,
-                cloudSyncEnabled: Boolean(state.cloudSyncEnabled)
-            });
         }
         catch {
-            logSyncDebug('workspace_sync_state_read_exception', {
-                workspaceId,
-                readCount
-            });
-        }
-    }, [
-        currentWorkspaceId,
-        setWorkspaceCloudSyncEnabled,
-        setWorkspaceSyncSourceOfTruth,
-        setWorkspaceSyncOnboardingCompleted,
-        setUserGlobalLastSyncedAt,
-        setWorkspaceLastPullAt,
-        setWorkspaceLastPushAt
-    ]);
-    const applyWorkspaceSyncStateSnapshot = useCallback((nextState) => {
-        const enabled = Boolean(nextState.cloudSyncEnabled);
-        setWorkspaceCloudSyncEnabled(enabled);
-        const source = nextState.sourceOfTruth === 'cloud' || nextState.sourceOfTruth === 'local'
-            ? nextState.sourceOfTruth
-            : null;
-        setWorkspaceSyncSourceOfTruth(source);
-        setWorkspaceSyncOnboardingCompleted(Boolean(nextState.onboardingCompleted));
-        if (typeof nextState.pullCursor === 'string') {
-            const trimmed = nextState.pullCursor.trim();
-            workspacePullCursorRef.current = trimmed.length > 0 ? trimmed : null;
+            // best-effort only; local runtime should continue
         }
-        else if (nextState.pullCursor === null) {
-            workspacePullCursorRef.current = null;
-        }
-    }, [
-        setWorkspaceCloudSyncEnabled,
-        setWorkspaceSyncSourceOfTruth,
-        setWorkspaceSyncOnboardingCompleted
-    ]);
+    }, [applyWorkspaceSyncStateSnapshot, currentWorkspaceId, persistWorkspaceSyncPatch]);
     const saveWorkspaceCloudSyncSettings = useCallback(async (nextState, deps) => {
         if (!isValidWorkspaceKey(currentWorkspaceId)) {
             return { success: false, error: 'Workspace setup is required before enabling sync.' };
         }
-        const nextEnabled = Boolean(nextState.enabled);
-        const nextSource = nextState.sourceOfTruth === 'cloud' || nextState.sourceOfTruth === 'local'
-            ? nextState.sourceOfTruth
-            : null;
-        let resolvedSource = nextSource;
-        // I6: when enabling sync, always start with onboardingCompleted=false so the
-        // orchestrator can verify the first pull succeeds before marking it complete.
-        // When disabling, preserve whatever the caller passes (usually the current value).
-        const nextOnboardingCompleted = nextEnabled ? false : Boolean(nextState.onboardingCompleted);
         try {
-            if (nextEnabled) {
-                if (!deps.isAuthenticated) {
-                    return { success: false, error: 'Sign in is required before enabling workspace sync.' };
-                }
-                if (!deps.cloudAuthConfigured) {
-                    return { success: false, error: 'Cloud authentication endpoint is not configured.' };
-                }
-                const ensured = await deps.ensureCloudWorkspaceReadyForSync();
-                if (!ensured.success) {
-                    return { success: false, error: ensured.error || 'Workspace sync handshake failed.' };
-                }
-                const shouldBootstrapLocal = nextSource === 'local'
-                    || (nextSource === null && ensured.provisioned === true);
-                if (resolvedSource === null) {
-                    resolvedSource = shouldBootstrapLocal ? 'local' : 'cloud';
-                }
-                if (shouldBootstrapLocal) {
-                    const snapshot = await deps.fetchLocalWorkspaceSnapshot();
-                    if (snapshot.error) {
-                        return { success: false, error: snapshot.error };
-                    }
-                    const [taxonomiesRes, documentsRes] = await Promise.allSettled([
-                        fetch('/api/taskforce/taxonomies', { method: 'GET', credentials: 'include' })
-                            .then((r) => r.ok
-                            ? r.json().catch(() => ({}))
-                            : Promise.resolve({}))
-                            .catch(() => ({})),
-                        fetch('/api/taskforce/sync/workspace/documents', { method: 'GET', credentials: 'include' })
-                            .then((r) => r.ok
-                            ? r.json().catch(() => ({}))
-                            : Promise.resolve({}))
-                            .catch(() => ({}))
-                    ]);
-                    const taxonomies = taxonomiesRes.status === 'fulfilled' && Array.isArray(taxonomiesRes.value?.taxonomies)
-                        ? taxonomiesRes.value.taxonomies
-                        : undefined;
-                    const documents = documentsRes.status === 'fulfilled' && Array.isArray(documentsRes.value?.documents)
-                        ? documentsRes.value.documents
-                            .filter((doc) => {
-                            if (!doc || typeof doc !== 'object')
-                                return false;
-                            const candidate = doc;
-                            return typeof candidate.path === 'string'
-                                && typeof candidate.updatedAt === 'string'
-                                && typeof candidate.content === 'string';
-                        })
-                        : undefined;
-                    const bootstrapRes = await bootstrapPushWorkspaceSnapshot(deps.resolveCloudAuthUrl, {
-                        workspaceId: currentWorkspaceId,
-                        tasks: snapshot.tasks,
-                        archived: snapshot.archived,
-                        taxonomies,
-                        documents
-                    });
-                    if (!bootstrapRes.ok) {
-                        const data = (bootstrapRes.data && typeof bootstrapRes.data === 'object')
-                            ? bootstrapRes.data
-                            : {};
-                        return {
-                            success: false,
-                            error: String(data.error || `Workspace bootstrap push failed (${bootstrapRes.status})`)
-                        };
-                    }
-                }
+            if (!nextState.enabled) {
+                await persistWorkspaceSyncPatch({
+                    enabled: false,
+                    phase: 'idle',
+                    pullCursor: null
+                });
+                return { success: true };
+            }
+            if (!deps.isAuthenticated) {
+                return { success: false, error: 'Sign in is required before enabling workspace sync.' };
+            }
+            if (!deps.cloudAuthConfigured) {
+                return { success: false, error: 'Cloud authentication endpoint is not configured.' };
+            }
+            const ensured = await deps.ensureCloudWorkspaceReadyForSync();
+            if (!ensured.success) {
+                return { success: false, error: ensured.error || 'Workspace sync handshake failed.' };
             }
             await persistWorkspaceSyncPatch({
-                cloudSyncEnabled: nextEnabled,
-                sourceOfTruth: resolvedSource,
-                onboardingCompleted: nextOnboardingCompleted
+                enabled: true,
+                phase: ensured.provisioned ? 'provision-local' : 'attach-cloud',
+                pullCursor: null,
+                lastPullAt: null,
+                lastPushAt: null,
+                lastSyncedAt: null
             });
-            setWorkspaceCloudSyncEnabled(nextEnabled);
-            setWorkspaceSyncSourceOfTruth(resolvedSource);
-            setWorkspaceSyncOnboardingCompleted(nextOnboardingCompleted);
             return { success: true };
         }
         catch {
             return { success: false, error: 'Failed to save workspace sync settings.' };
         }
-    }, [
-        setWorkspaceCloudSyncEnabled,
-        setWorkspaceSyncSourceOfTruth,
-        setWorkspaceSyncOnboardingCompleted,
-        persistWorkspaceSyncPatch
-    ]);
+    }, [currentWorkspaceId, persistWorkspaceSyncPatch]);
     useEffect(() => {
         workspaceLastPushedSignatureRef.current = '';
         workspacePendingSignatureRef.current = '';
         workspaceLastPushedTaskIdsRef.current = new Set();
         workspaceDeletedTaskIdsRef.current = new Set();
         workspacePullCursorRef.current = null;
-        workspacePullBootstrapDoneRef.current = false;
-        workspaceSyncStateReadCountRef.current = 0;
-        workspaceBackfillForcedRef.current.delete(currentWorkspaceId);
-        workspaceSyncReadyRef.current.delete(currentWorkspaceId);
-        workspaceCloudHydratedRef.current.delete(currentWorkspaceId);
-        workspaceRetryAttemptRef.current = 0;
-        workspaceRetryAtMsRef.current = null;
+        workspaceSyncStateRef.current = createDefaultWorkspaceSyncState();
         workspacePushInFlightRef.current = false;
         workspacePullInFlightRef.current = false;
-        setWorkspaceSyncReady(false);
-        setWorkspaceCloudHydrated(false);
-        setWorkspaceSyncFailureCount(0);
-        setWorkspaceSyncRetryScheduledCount(0);
-        setWorkspaceSyncAuthFailureCount(0);
-        setWorkspaceSyncLastFailureSource(null);
-        setWorkspaceSyncLastFailureStatusCode(null);
-        setWorkspaceBootstrapSyncInProgress(false);
-        setWorkspaceBootstrapSyncPages(0);
-        setWorkspaceBootstrapSyncAppliedChanges(0);
-        if (workspaceRetryTimerRef.current !== null && typeof window !== 'undefined') {
-            window.clearTimeout(workspaceRetryTimerRef.current);
-            workspaceRetryTimerRef.current = null;
-        }
-        if (activeLockAbortControllerRef.current) {
-            activeLockAbortControllerRef.current.abort();
-            activeLockAbortControllerRef.current = null;
-        }
-        activeLockWorkspaceIdRef.current = null;
-        setWorkspaceRetryAt(null);
-    }, [currentWorkspaceId, setWorkspaceSyncReady, setWorkspaceCloudHydrated]);
+        releaseWorkspaceSyncLease();
+        clearWorkspaceRetry();
+    }, [clearWorkspaceRetry, currentWorkspaceId, releaseWorkspaceSyncLease]);
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof BroadcastChannel === 'undefined')
+            return;
+        const channel = new BroadcastChannel(WORKSPACE_SYNC_LEASE_CHANNEL);
+        workspaceSyncLeaseChannelRef.current = channel;
+        return () => {
+            channel.close();
+            if (workspaceSyncLeaseChannelRef.current === channel) {
+                workspaceSyncLeaseChannelRef.current = null;
+            }
+        };
+    }, []);
     useEffect(() => {
         return () => {
             if (workspaceRetryTimerRef.current !== null && typeof window !== 'undefined') {
                 window.clearTimeout(workspaceRetryTimerRef.current);
                 workspaceRetryTimerRef.current = null;
             }
-            if (activeLockAbortControllerRef.current) {
-                activeLockAbortControllerRef.current.abort();
-                activeLockAbortControllerRef.current = null;
-            }
-            activeLockWorkspaceIdRef.current = null;
+            releaseWorkspaceSyncLease();
         };
-    }, []);
+    }, [releaseWorkspaceSyncLease]);
     return {
         workspaceRetryAt,
-        setWorkspaceRetryAt,
-        isWorkspacePullRetryPending,
-        workspaceBootstrapSyncInProgress,
-        setWorkspaceBootstrapSyncInProgress,
-        workspaceBootstrapSyncPages,
-        setWorkspaceBootstrapSyncPages,
-        workspaceBootstrapSyncAppliedChanges,
-        setWorkspaceBootstrapSyncAppliedChanges,
-        workspaceSyncFailureCount,
-        workspaceSyncRetryScheduledCount,
-        workspaceSyncAuthFailureCount,
-        workspaceSyncLastFailureSource,
-        workspaceSyncLastFailureStatusCode,
+        isWorkspaceRetryPending,
         workspacePushInFlightRef,
         workspacePullInFlightRef,
         workspaceLastPushedSignatureRef,
@@ -578,21 +403,15 @@ export function useWorkspaceSyncController(input) {
         workspaceLastPushedTaskIdsRef,
         workspaceDeletedTaskIdsRef,
         workspacePullCursorRef,
-        workspacePullBootstrapDoneRef,
-        workspaceBackfillForcedRef,
-        workspaceSyncReadyRef,
-        workspaceCloudHydratedRef,
         clearWorkspaceRetry,
-        scheduleWorkspacePullRetry,
-        isWorkspacePullCooldownActive,
-        markWorkspacePullCooldown,
-        tryAcquireWorkspacePullLease,
-        releaseWorkspacePullLease,
-        recordWorkspaceSyncFailure,
-        incrementWorkspaceSyncAuthFailure,
+        scheduleWorkspaceRetry,
         persistWorkspaceSyncPatch,
         loadWorkspaceSyncState,
         applyWorkspaceSyncStateSnapshot,
-        saveWorkspaceCloudSyncSettings
+        saveWorkspaceCloudSyncSettings,
+        acquireWorkspaceSyncLease,
+        releaseWorkspaceSyncLease,
+        forceClearWorkspaceSyncLease,
+        readWorkspaceSyncLease
     };
 }