@taskforcehq/taskforce 0.3.303 → 0.3.305

package/dist/hooks/workspace/useTaskforceWorkspaceBootstrap.js

@@ -0,0 +1,434 @@
+import { useCallback, useEffect } from 'react';
+import { createDefaultAssigneeOptions, createWorkspaceAssigneeOptions, mergeAssigneeOptions } from '../../utils/assignees';
+import { hasWorkspaceTaxonomyStatePayload, normalizeWorkspaceTaxonomyStatePayload } from '../../shared/taxonomyState.js';
+import { logBootstrapDebug, readPersistedWorkspaceId } from './workspaceLocalState';
+export function useTaskforceWorkspaceBootstrap(args) {
+    const { shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls, getWorkspaceRequestState, isWorkspaceRequestStale, isWorkspaceEpochStale, isAbortError, isBootstrapTimeoutError, fetchWithTimeout, handleUnauthorized, applyBootstrapConfig, loadPersistedUiState, fetchBuildInfo, markBootstrapPhase, markBootstrapStalled, fetchWorkflows, fetchInitiativeTemplates, loadAvailableEnvironments, setReferenceDataLoaded, setCustomCategories, setCustomTypes, setPriorities, setTaxonomies, setTaxonomyDisplayLabels, setConfigLoaded, hasLoadedUiStateRef, currentWorkspaceIdRef, referenceDataRequestRef, referenceDataAbortRef, bootstrapConfigAbortRef, workspaceListAbortRef, assigneeOptionsAbortRef, workspaceListHydratedRef, setAvailableWorkspaces, runtimeMode, applyResolvedWorkspaceId, workspaceSwitchingEnabled, authSessionResolved, isAuthenticated, authUserId, setHydratedWorkspaceRole, setAssigneeOptions, setAssigneeOptionsLoaded, commitCurrentWorkspaceId, currentWorkspaceId, workspaceSelectionScope, abortWorkspaceScopedRequests, setWorkspaceBootstrapPending, checkAuthSession, lastConfigRefreshKeyRef, lastAssigneeOptionsLoadKeyRef, lastWorkspaceSyncStateLoadKeyRef, lastTaskSurfaceLoadKeyRef, lastSettingsSurfaceLoadKeyRef, isOpen, activeTab, showArchive, taskScope, settingsSection, fetchTasks, fetchArchive, fetchPlanningEntities, refreshTaskCollections, loadWorkspaceSyncState, archiveBootstrapTimerRef, hasBootstrappedDataRef } = args;
+    const fetchReferenceData = useCallback(async (options) => {
+        const ignoreAuthGuard = options?.ignoreAuthGuard === true;
+        const force = options?.force === true;
+        if (!ignoreAuthGuard && (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls))
+            return;
+        const requestState = getWorkspaceRequestState();
+        if (!force && referenceDataRequestRef.current?.workspaceId === requestState.workspaceId) {
+            await referenceDataRequestRef.current.promise;
+            return;
+        }
+        setReferenceDataLoaded(false);
+        const abortController = new AbortController();
+        referenceDataAbortRef.current = abortController;
+        const request = (async () => {
+            await Promise.allSettled([
+                (async () => {
+                    const taxonomyRes = await fetch('/api/taskforce/taxonomy-state', { signal: abortController.signal });
+                    if (!taxonomyRes.ok)
+                        return;
+                    const taxonomyData = await taxonomyRes.json().catch(() => ({}));
+                    if (!hasWorkspaceTaxonomyStatePayload(taxonomyData)) {
+                        const [catRes, typeRes, priorityRes, taxRes] = await Promise.all([
+                            fetch('/api/taskforce/categories', { signal: abortController.signal }),
+                            fetch('/api/taskforce/types', { signal: abortController.signal }),
+                            fetch('/api/taskforce/priorities', { signal: abortController.signal }),
+                            fetch('/api/taskforce/taxonomies', { signal: abortController.signal })
+                        ]);
+                        const [catData, typeData, priorityData, taxData] = await Promise.all([
+                            catRes.ok ? catRes.json().catch(() => ({})) : Promise.resolve({}),
+                            typeRes.ok ? typeRes.json().catch(() => ({})) : Promise.resolve({}),
+                            priorityRes.ok ? priorityRes.json().catch(() => ({})) : Promise.resolve({}),
+                            taxRes.ok ? taxRes.json().catch(() => ({})) : Promise.resolve({})
+                        ]);
+                        taxonomyData.categories = catData.categories;
+                        taxonomyData.types = typeData.types;
+                        taxonomyData.priorities = priorityData.priorities;
+                        taxonomyData.taxonomies = taxData.taxonomies;
+                    }
+                    const normalized = normalizeWorkspaceTaxonomyStatePayload(taxonomyData);
+                    if (isWorkspaceRequestStale(requestState))
+                        return;
+                    if (normalized.categories.length > 0)
+                        setCustomCategories(normalized.categories);
+                    if (normalized.types.length > 0)
+                        setCustomTypes(normalized.types);
+                    if (normalized.priorities.length > 0)
+                        setPriorities(normalized.priorities);
+                    setTaxonomies(normalized.taxonomies);
+                    setTaxonomyDisplayLabels(normalized.displayLabels || {});
+                })(),
+                fetchWorkflows(),
+                fetchInitiativeTemplates(),
+                loadAvailableEnvironments()
+            ]);
+            if (isWorkspaceRequestStale(requestState))
+                return;
+            setReferenceDataLoaded(true);
+        })();
+        referenceDataRequestRef.current = { workspaceId: requestState.workspaceId, promise: request };
+        try {
+            await request;
+        }
+        finally {
+            if (referenceDataRequestRef.current?.promise === request)
+                referenceDataRequestRef.current = null;
+            if (referenceDataAbortRef.current === abortController)
+                referenceDataAbortRef.current = null;
+        }
+    }, [fetchInitiativeTemplates, fetchWorkflows, getWorkspaceRequestState, isWorkspaceRequestStale, loadAvailableEnvironments, referenceDataAbortRef, referenceDataRequestRef, setCustomCategories, setCustomTypes, setPriorities, setReferenceDataLoaded, setTaxonomies, setTaxonomyDisplayLabels, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
+    const fetchBootstrapConfig = useCallback(async (options) => {
+        const ignoreAuthGuard = options?.ignoreAuthGuard === true;
+        if (!ignoreAuthGuard && (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls))
+            return;
+        markBootstrapPhase('config');
+        const requestState = getWorkspaceRequestState();
+        const abortController = new AbortController();
+        bootstrapConfigAbortRef.current = abortController;
+        try {
+            const res = await fetchWithTimeout('/api/taskforce/config', undefined, 12000, { signal: abortController.signal });
+            if (isWorkspaceEpochStale(requestState))
+                return;
+            if (res.status === 401) {
+                handleUnauthorized();
+                setConfigLoaded(true);
+                return;
+            }
+            let configResolvedWorkspaceId = '';
+            if (res.ok) {
+                const data = await res.json();
+                if (isWorkspaceEpochStale(requestState))
+                    return;
+                configResolvedWorkspaceId = typeof data?.workspaceId === 'string' && data.workspaceId.trim().length > 0 ? data.workspaceId.trim() : '';
+                applyBootstrapConfig(data);
+            }
+            if (isWorkspaceEpochStale(requestState)) {
+                const liveWorkspaceId = String(currentWorkspaceIdRef.current || 'default').trim() || 'default';
+                if (!configResolvedWorkspaceId || liveWorkspaceId !== configResolvedWorkspaceId)
+                    return;
+            }
+            if (!hasLoadedUiStateRef.current) {
+                hasLoadedUiStateRef.current = true;
+                await loadPersistedUiState(configResolvedWorkspaceId || requestState.workspaceId);
+            }
+            if (isWorkspaceEpochStale(requestState)) {
+                const liveWorkspaceId = String(currentWorkspaceIdRef.current || 'default').trim() || 'default';
+                if (!configResolvedWorkspaceId || liveWorkspaceId !== configResolvedWorkspaceId)
+                    return;
+            }
+            setConfigLoaded(true);
+            markBootstrapPhase('ready');
+            void fetchBuildInfo();
+        }
+        catch (error) {
+            if (isAbortError(error) || isWorkspaceEpochStale(requestState))
+                return;
+            if (!hasLoadedUiStateRef.current) {
+                hasLoadedUiStateRef.current = true;
+                await loadPersistedUiState(requestState.workspaceId);
+            }
+            markBootstrapStalled(isBootstrapTimeoutError(error) ? 'Startup checks timed out.' : 'Unable to finish startup checks.');
+            setConfigLoaded(true);
+        }
+        finally {
+            if (bootstrapConfigAbortRef.current === abortController)
+                bootstrapConfigAbortRef.current = null;
+        }
+    }, [applyBootstrapConfig, bootstrapConfigAbortRef, currentWorkspaceIdRef, fetchBuildInfo, fetchWithTimeout, getWorkspaceRequestState, handleUnauthorized, hasLoadedUiStateRef, isAbortError, isBootstrapTimeoutError, isWorkspaceEpochStale, loadPersistedUiState, markBootstrapPhase, markBootstrapStalled, setConfigLoaded, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
+    const fetchConfig = useCallback(async (options) => {
+        await fetchBootstrapConfig(options);
+        await fetchReferenceData(options);
+    }, [fetchBootstrapConfig, fetchReferenceData]);
+    const fetchWorkspaces = useCallback(async () => {
+        if (!workspaceSwitchingEnabled) {
+            setAvailableWorkspaces([]);
+            workspaceListHydratedRef.current = false;
+            return { success: true, workspaces: [] };
+        }
+        const requestState = getWorkspaceRequestState();
+        const abortController = new AbortController();
+        workspaceListAbortRef.current = abortController;
+        try {
+            const res = await fetchWithTimeout('/api/taskforce/workspaces', { method: 'GET', credentials: 'include' }, 12000, { signal: abortController.signal });
+            if (isWorkspaceEpochStale(requestState))
+                return { success: false, error: 'Workspace changed while loading workspaces.' };
+            if (res.status === 401) {
+                setAvailableWorkspaces([]);
+                workspaceListHydratedRef.current = false;
+                return { success: false, error: 'Authentication required.' };
+            }
+            const data = await res.json().catch(() => ({}));
+            if (isWorkspaceEpochStale(requestState))
+                return { success: false, error: 'Workspace changed while loading workspaces.' };
+            if (!res.ok || data?.success === false) {
+                setAvailableWorkspaces([]);
+                workspaceListHydratedRef.current = false;
+                return { success: false, error: data?.error || `Failed to load workspaces (${res.status})` };
+            }
+            const workspaces = Array.isArray(data?.workspaces)
+                ? data.workspaces.map((workspace) => ({
+                    id: String(workspace?.id || '').trim(),
+                    name: String(workspace?.name || '').trim(),
+                    role: String(workspace?.role || 'member').trim().toLowerCase(),
+                    slug: typeof workspace?.slug === 'string' ? workspace.slug : null,
+                    description: typeof workspace?.description === 'string' ? workspace.description : null,
+                    status: typeof workspace?.status === 'string' ? workspace.status : '',
+                    betaAccess: workspace?.betaAccess === true
+                })).filter((workspace) => workspace.id && workspace.name)
+                : [];
+            setAvailableWorkspaces(workspaces);
+            workspaceListHydratedRef.current = true;
+            if (runtimeMode !== 'local' && typeof data?.currentWorkspaceId === 'string' && data.currentWorkspaceId.trim().length > 0) {
+                applyResolvedWorkspaceId(data.currentWorkspaceId.trim(), { preserveNonDefaultDefault: true });
+            }
+            return { success: true, workspaces };
+        }
+        catch (error) {
+            if (isBootstrapTimeoutError(error))
+                markBootstrapStalled('Startup checks timed out.');
+            setAvailableWorkspaces([]);
+            workspaceListHydratedRef.current = false;
+            return { success: false, error: isAbortError(error) ? 'Workspace list request aborted.' : 'Failed to load workspaces.' };
+        }
+        finally {
+            if (workspaceListAbortRef.current === abortController)
+                workspaceListAbortRef.current = null;
+        }
+    }, [applyResolvedWorkspaceId, fetchWithTimeout, getWorkspaceRequestState, isAbortError, isBootstrapTimeoutError, isWorkspaceEpochStale, markBootstrapStalled, runtimeMode, setAvailableWorkspaces, workspaceListAbortRef, workspaceListHydratedRef, workspaceSwitchingEnabled]);
+    const fetchAssigneeOptions = useCallback(async () => {
+        const requestState = getWorkspaceRequestState();
+        const abortController = new AbortController();
+        assigneeOptionsAbortRef.current = abortController;
+        setAssigneeOptionsLoaded(false);
+        try {
+            const [assigneeResult, workspaceMembersResult] = await Promise.all([
+                fetchWithTimeout('/api/taskforce/workspace/assignee-options', { method: 'GET', credentials: 'include' }, 12000, { signal: abortController.signal }),
+                (authSessionResolved && isAuthenticated)
+                    ? fetchWithTimeout('/api/taskforce/auth/workspace-members', { method: 'GET', credentials: 'include' }, 12000, { signal: abortController.signal }).catch(() => null)
+                    : Promise.resolve(null)
+            ]);
+            if (isWorkspaceRequestStale(requestState))
+                return { success: false, error: 'Workspace changed while loading assignee options.' };
+            if (assigneeResult.status === 401) {
+                setAssigneeOptions(createDefaultAssigneeOptions());
+                setAssigneeOptionsLoaded(true);
+                return { success: false, error: 'Authentication required.' };
+            }
+            const data = await assigneeResult.json().catch(() => ({}));
+            if (isWorkspaceRequestStale(requestState))
+                return { success: false, error: 'Workspace changed while loading assignee options.' };
+            if (!assigneeResult.ok) {
+                setAssigneeOptions(createDefaultAssigneeOptions());
+                setAssigneeOptionsLoaded(true);
+                return { success: false, error: data?.error || `Failed to load assignee options (${assigneeResult.status})` };
+            }
+            const assignees = Array.isArray(data?.assignees) ? data.assignees : [];
+            const directOptions = assignees.map((entry) => {
+                const value = String(entry?.value || '').trim();
+                const kindRaw = String(entry?.kind || '').trim().toLowerCase();
+                if (!value)
+                    return null;
+                if (kindRaw === 'agent' || kindRaw === 'ai')
+                    return { value, label: String(entry?.label || value).trim() || value, icon: String(entry?.icon || 'Bot'), color: String(entry?.color || '#8b5cf6'), kind: 'agent' };
+                if (kindRaw === 'member' || kindRaw === 'human')
+                    return { value, label: String(entry?.label || value).trim() || value, icon: String(entry?.icon || 'User'), color: String(entry?.color || '#22c55e'), kind: 'member' };
+                return null;
+            }).filter(Boolean);
+            const fallbackCandidates = assignees.map((candidate) => ({
+                userId: String(candidate?.userId || '').trim(),
+                email: String(candidate?.email || '').trim().toLowerCase(),
+                displayName: typeof candidate?.displayName === 'string' ? candidate.displayName : null
+            })).filter((candidate) => candidate.userId);
+            let memberCandidates = fallbackCandidates;
+            if (workspaceMembersResult?.ok) {
+                const workspaceMembersData = await workspaceMembersResult.json().catch(() => ({}));
+                const users = Array.isArray(workspaceMembersData?.users) ? workspaceMembersData.users : [];
+                const normalizedAuthUserId = String(authUserId || '').trim();
+                const currentMember = users.find((candidate) => String(candidate?.userId || '').trim() === normalizedAuthUserId);
+                const currentMemberRole = String(currentMember?.role || '').trim().toLowerCase();
+                if (currentMemberRole === 'owner' || currentMemberRole === 'admin' || currentMemberRole === 'member' || currentMemberRole === 'read-only') {
+                    setHydratedWorkspaceRole(currentMemberRole);
+                }
+                else if (!workspaceSwitchingEnabled && users.length === 0) {
+                    setHydratedWorkspaceRole(null);
+                }
+                const workspaceMemberCandidates = users.map((candidate) => ({
+                    userId: String(candidate?.userId || '').trim(),
+                    email: String(candidate?.email || '').trim().toLowerCase(),
+                    displayName: typeof candidate?.displayName === 'string' ? candidate.displayName : null
+                })).filter((candidate) => candidate.userId);
+                memberCandidates = Array.from(new Map([...fallbackCandidates, ...workspaceMemberCandidates].map((candidate) => [candidate.userId, candidate])).values());
+            }
+            else if (!workspaceSwitchingEnabled && !fallbackCandidates.length) {
+                setHydratedWorkspaceRole(null);
+            }
+            const merged = mergeAssigneeOptions([...directOptions, ...createWorkspaceAssigneeOptions(memberCandidates).filter((option) => option.kind === 'member')]);
+            if (isWorkspaceRequestStale(requestState))
+                return { success: false, error: 'Workspace changed while loading assignee options.' };
+            setAssigneeOptions(merged);
+            setAssigneeOptionsLoaded(true);
+            return { success: true };
+        }
+        catch (error) {
+            if (!isWorkspaceRequestStale(requestState)) {
+                setAssigneeOptions(createDefaultAssigneeOptions());
+                setAssigneeOptionsLoaded(true);
+            }
+            return { success: false, error: isAbortError(error) ? 'Assignee options request aborted.' : 'Failed to load assignee options.' };
+        }
+        finally {
+            if (assigneeOptionsAbortRef.current === abortController)
+                assigneeOptionsAbortRef.current = null;
+        }
+    }, [assigneeOptionsAbortRef, authSessionResolved, authUserId, fetchWithTimeout, getWorkspaceRequestState, isAbortError, isAuthenticated, isWorkspaceRequestStale, setAssigneeOptions, setAssigneeOptionsLoaded, setHydratedWorkspaceRole, workspaceSwitchingEnabled]);
+    const switchWorkspace = useCallback(async (workspaceId, options) => {
+        if (!workspaceSwitchingEnabled)
+            return { success: false, error: 'Workspace switching is unavailable in local mode.', code: 'WORKSPACE_SWITCHING_DISABLED' };
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedWorkspaceId)
+            return { success: false, error: 'workspaceId is required.' };
+        try {
+            const res = await fetch('/api/taskforce/session/workspace', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                credentials: 'include',
+                body: JSON.stringify({ workspaceId: normalizedWorkspaceId })
+            });
+            const data = await res.json().catch(() => ({}));
+            if (!res.ok || data?.success === false)
+                return { success: false, error: data?.error || `Failed to switch workspace (${res.status})`, code: data?.code };
+            commitCurrentWorkspaceId(normalizedWorkspaceId, { clearExplicitSelection: false });
+            abortWorkspaceScopedRequests();
+            setWorkspaceBootstrapPending(true);
+            markBootstrapPhase('workspace');
+            const authenticated = await checkAuthSession({ force: true });
+            if (options?.hydrate === false) {
+                await fetchWorkspaces();
+            }
+            else {
+                lastConfigRefreshKeyRef.current = `${runtimeMode}:${normalizedWorkspaceId}:${workspaceSelectionScope}`;
+                lastAssigneeOptionsLoadKeyRef.current = `${runtimeMode}:${authenticated ? 'auth' : 'guest'}:${normalizedWorkspaceId}`;
+                lastWorkspaceSyncStateLoadKeyRef.current = normalizedWorkspaceId;
+                if (isOpen && activeTab === 'tasks')
+                    lastTaskSurfaceLoadKeyRef.current = `${normalizedWorkspaceId}:${activeTab}:${showArchive ? 'archive' : 'active'}:${taskScope}`;
+                if (isOpen && activeTab === 'settings')
+                    lastSettingsSurfaceLoadKeyRef.current = `${normalizedWorkspaceId}:${activeTab}:${settingsSection}`;
+                await Promise.all([fetchConfig(), fetchWorkspaces(), refreshTaskCollections({ isSilent: false }), fetchAssigneeOptions(), loadWorkspaceSyncState()]);
+            }
+            return { success: true };
+        }
+        catch {
+            return { success: false, error: 'Failed to switch workspace.' };
+        }
+        finally {
+            setWorkspaceBootstrapPending(false);
+        }
+    }, [abortWorkspaceScopedRequests, activeTab, checkAuthSession, commitCurrentWorkspaceId, fetchAssigneeOptions, fetchConfig, fetchWorkspaces, isOpen, lastAssigneeOptionsLoadKeyRef, lastConfigRefreshKeyRef, lastSettingsSurfaceLoadKeyRef, lastTaskSurfaceLoadKeyRef, lastWorkspaceSyncStateLoadKeyRef, loadWorkspaceSyncState, markBootstrapPhase, refreshTaskCollections, runtimeMode, settingsSection, setWorkspaceBootstrapPending, showArchive, taskScope, workspaceSelectionScope, workspaceSwitchingEnabled]);
+    const resolveWorkspaceAfterAuth = useCallback(async (options) => {
+        markBootstrapPhase('workspace');
+        setWorkspaceBootstrapPending(true);
+        try {
+            if (!workspaceSwitchingEnabled) {
+                const localWorkspaceId = String(currentWorkspaceId || '').trim() || 'default';
+                commitCurrentWorkspaceId(localWorkspaceId);
+                return { success: true, workspaceSetupRequired: false, workspaceId: localWorkspaceId };
+            }
+            const preferredWorkspaceId = String(options?.preferredWorkspaceId || '').trim();
+            const persistedWorkspaceId = readPersistedWorkspaceId(workspaceSelectionScope);
+            const workspacesResult = await fetchWorkspaces();
+            if (!workspacesResult.success)
+                return { success: false, workspaceSetupRequired: false, error: workspacesResult.error || 'Failed to load workspaces after authentication.' };
+            const workspaces = Array.isArray(workspacesResult.workspaces) ? workspacesResult.workspaces : [];
+            if (workspaces.length === 0) {
+                commitCurrentWorkspaceId('default');
+                return { success: true, workspaceSetupRequired: true };
+            }
+            const ids = new Set(workspaces.map((workspace) => String(workspace.id || '').trim()).filter(Boolean));
+            const selectedWorkspaceId = (preferredWorkspaceId && ids.has(preferredWorkspaceId) ? preferredWorkspaceId : '') || (persistedWorkspaceId && ids.has(persistedWorkspaceId) ? persistedWorkspaceId : '') || String(workspaces[0]?.id || '').trim();
+            if (!selectedWorkspaceId) {
+                commitCurrentWorkspaceId('default');
+                return { success: true, workspaceSetupRequired: true };
+            }
+            const current = String(currentWorkspaceIdRef.current || '').trim();
+            if (current !== selectedWorkspaceId) {
+                const switched = await switchWorkspace(selectedWorkspaceId, { hydrate: false });
+                if (!switched.success)
+                    return { success: false, workspaceSetupRequired: false, error: switched.error || 'Failed to set workspace after authentication.', code: switched.code };
+            }
+            else {
+                commitCurrentWorkspaceId(selectedWorkspaceId);
+            }
+            return { success: true, workspaceSetupRequired: false, workspaceId: selectedWorkspaceId };
+        }
+        catch {
+            markBootstrapStalled('Unable to resolve workspace access.');
+            return { success: false, workspaceSetupRequired: false, error: 'Failed to resolve workspace access.' };
+        }
+        finally {
+            setWorkspaceBootstrapPending(false);
+        }
+    }, [commitCurrentWorkspaceId, currentWorkspaceId, currentWorkspaceIdRef, fetchWorkspaces, markBootstrapPhase, markBootstrapStalled, setWorkspaceBootstrapPending, switchWorkspace, workspaceSelectionScope, workspaceSwitchingEnabled]);
+    const retryBootstrapChecks = useCallback(async () => {
+        markBootstrapPhase('auth');
+        const authenticated = await checkAuthSession({ force: true });
+        if (workspaceSwitchingEnabled && authenticated) {
+            const workspaceResolution = await resolveWorkspaceAfterAuth();
+            if (!workspaceResolution.success || workspaceResolution.workspaceSetupRequired) {
+                await fetchConfig({ ignoreAuthGuard: true });
+                return;
+            }
+        }
+        await fetchConfig({ ignoreAuthGuard: true });
+    }, [checkAuthSession, fetchConfig, markBootstrapPhase, resolveWorkspaceAfterAuth, workspaceSwitchingEnabled]);
+    useEffect(() => {
+        if (!shouldDeferProtectedApiCalls && !shouldBlockProtectedApiCalls && !hasBootstrappedDataRef.current) {
+            hasBootstrappedDataRef.current = true;
+            void (async () => {
+                if (runtimeMode === 'cloud' && authSessionResolved && isAuthenticated) {
+                    const workspaceResolution = await resolveWorkspaceAfterAuth();
+                    if (!workspaceResolution.success || workspaceResolution.workspaceSetupRequired) {
+                        await fetchBootstrapConfig();
+                        void fetchReferenceData();
+                        return;
+                    }
+                }
+                await fetchBootstrapConfig();
+                await Promise.all([fetchTasks(false), fetchReferenceData(), fetchPlanningEntities()]);
+                if (typeof window !== 'undefined') {
+                    if (archiveBootstrapTimerRef.current !== null)
+                        window.clearTimeout(archiveBootstrapTimerRef.current);
+                    archiveBootstrapTimerRef.current = window.setTimeout(() => {
+                        archiveBootstrapTimerRef.current = null;
+                        void fetchArchive(true).then(() => logBootstrapDebug('bootstrap_archive_loaded_deferred', {}));
+                    }, 1500);
+                }
+            })();
+        }
+    }, [archiveBootstrapTimerRef, authSessionResolved, fetchArchive, fetchBootstrapConfig, fetchPlanningEntities, fetchReferenceData, fetchTasks, hasBootstrappedDataRef, isAuthenticated, resolveWorkspaceAfterAuth, runtimeMode, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
+    useEffect(() => {
+        if (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls || workspaceSelectionScope === 'bootstrap' || !hasBootstrappedDataRef.current)
+            return;
+        const loadKey = `${runtimeMode}:${currentWorkspaceId}:${workspaceSelectionScope}`;
+        if (lastConfigRefreshKeyRef.current === loadKey)
+            return;
+        lastConfigRefreshKeyRef.current = loadKey;
+        void fetchConfig();
+    }, [currentWorkspaceId, fetchConfig, hasBootstrappedDataRef, lastConfigRefreshKeyRef, runtimeMode, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls, workspaceSelectionScope]);
+    useEffect(() => {
+        if (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls)
+            return;
+        const loadKey = currentWorkspaceId;
+        if (lastWorkspaceSyncStateLoadKeyRef.current === loadKey)
+            return;
+        lastWorkspaceSyncStateLoadKeyRef.current = loadKey;
+        void loadWorkspaceSyncState();
+    }, [currentWorkspaceId, lastWorkspaceSyncStateLoadKeyRef, loadWorkspaceSyncState, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
+    useEffect(() => {
+        if (runtimeMode !== 'cloud' || !authSessionResolved || !isAuthenticated) {
+            if (runtimeMode !== 'cloud')
+                setAvailableWorkspaces([]);
+            workspaceListHydratedRef.current = false;
+            return;
+        }
+        if (!hasBootstrappedDataRef.current || workspaceListHydratedRef.current)
+            return;
+        void fetchWorkspaces();
+    }, [authSessionResolved, fetchWorkspaces, hasBootstrappedDataRef, isAuthenticated, runtimeMode, setAvailableWorkspaces, workspaceListHydratedRef]);
+    return { fetchReferenceData, fetchBootstrapConfig, fetchConfig, fetchWorkspaces, fetchAssigneeOptions, switchWorkspace, resolveWorkspaceAfterAuth, retryBootstrapChecks };
+}

package/dist/hooks/workspace/workspaceLocalState.d.ts

@@ -22,9 +22,28 @@ export interface PersistedUiState {
     lastCategory?: string;
     exportEnvironment?: string;
 }
+type RemoteUiStatePersistResult = {
+    skipped: boolean;
+    reason?: 'unchanged' | 'cooldown';
+    response?: Response;
+    payload?: any;
+};
 export declare function generateClientUuid(): string;
 export declare function logBootstrapDebug(event: string, details?: Record<string, unknown>): void;
+export declare function resetRemoteUiStatePersistCache(): void;
+export declare function persistRemoteUiState(input: {
+    stateKey?: string;
+    workspaceId?: string | null;
+    patch: object;
+    headers?: Record<string, string>;
+    throwOnError?: boolean;
+    failureRetryMs?: number;
+    skipIfUnchanged?: boolean;
+    respectFailureCooldown?: boolean;
+}): Promise<RemoteUiStatePersistResult>;
 export declare function readPersistedWorkspaceId(scopeRaw?: string): string;
 export declare function writePersistedWorkspaceId(workspaceId: string, scopeRaw?: string): void;
+export declare function clearPersistedWorkspaceId(scopeRaw?: string): void;
 export declare function readPersistedAppUiState(scopeRaw?: string): PersistedUiState | null;
 export declare function writePersistedAppUiState(state: PersistedUiState, scopeRaw?: string): void;
+export {};

package/dist/hooks/workspace/workspaceLocalState.js

@@ -2,6 +2,8 @@ import { isReservedWorkspaceId, normalizeWorkspaceStorageScope, normalizeWorkspa
 const WORKSPACE_CONTEXT_KEY_PREFIX = 'taskforce.workspaceContext.v2';
 const APP_UI_STATE_STORAGE_KEY_PREFIX = 'taskforce.uiState.app.v1';
 const BOOTSTRAP_DEBUG_LOG_KEY = 'taskforce.bootstrapDebug.v1';
+const REMOTE_UI_STATE_FAILURE_RETRY_MS = 5000;
+const remoteUiStatePersistCache = new Map();
 export function generateClientUuid() {
     if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
         return crypto.randomUUID();
@@ -25,6 +27,93 @@ export function logBootstrapDebug(event, details) {
     const payload = details && typeof details === 'object' ? details : {};
     console.info('[Taskforce Bootstrap]', event, payload);
 }
+function buildRemoteUiStatePersistKey(stateKeyRaw, workspaceIdRaw) {
+    const stateKey = String(stateKeyRaw || 'default').trim() || 'default';
+    const workspaceId = String(workspaceIdRaw || 'default').trim() || 'default';
+    return `${workspaceId}::${stateKey}`;
+}
+export function resetRemoteUiStatePersistCache() {
+    remoteUiStatePersistCache.clear();
+}
+export async function persistRemoteUiState(input) {
+    const stateKey = String(input.stateKey || 'default').trim() || 'default';
+    const workspaceId = String(input.workspaceId || '').trim();
+    const patch = input.patch && typeof input.patch === 'object' ? input.patch : {};
+    const serializedPatch = JSON.stringify(patch);
+    const persistKey = buildRemoteUiStatePersistKey(stateKey, workspaceId || 'default');
+    const now = Date.now();
+    const cached = remoteUiStatePersistCache.get(persistKey);
+    if (cached && cached.serializedPatch === serializedPatch) {
+        if (cached.status === 'success' && input.skipIfUnchanged !== false) {
+            logBootstrapDebug('ui_state_persist_skipped', {
+                stateKey,
+                workspaceId: workspaceId || 'default',
+                reason: 'unchanged'
+            });
+            return { skipped: true, reason: 'unchanged' };
+        }
+        if (input.respectFailureCooldown !== false && cached.retryAfter > now) {
+            logBootstrapDebug('ui_state_persist_skipped', {
+                stateKey,
+                workspaceId: workspaceId || 'default',
+                reason: 'cooldown',
+                retryAfterMs: cached.retryAfter - now
+            });
+            return { skipped: true, reason: 'cooldown' };
+        }
+    }
+    try {
+        const response = await fetch('/api/taskforce/ui-state', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...(input.headers || {}) },
+            credentials: 'include',
+            body: JSON.stringify({
+                stateKey,
+                ...(workspaceId ? { workspaceId } : {}),
+                patch
+            })
+        });
+        const payload = await response.json().catch(() => ({}));
+        if (response.ok && payload?.success !== false) {
+            remoteUiStatePersistCache.set(persistKey, {
+                serializedPatch,
+                status: 'success',
+                retryAfter: 0
+            });
+            return { skipped: false, response, payload };
+        }
+        remoteUiStatePersistCache.set(persistKey, {
+            serializedPatch,
+            status: 'failure',
+            retryAfter: now + (input.failureRetryMs ?? REMOTE_UI_STATE_FAILURE_RETRY_MS)
+        });
+        logBootstrapDebug('ui_state_persist_failed', {
+            stateKey,
+            workspaceId: workspaceId || 'default',
+            status: response.status,
+            error: String(payload?.error || '')
+        });
+        if (input.throwOnError) {
+            throw new Error(String(payload?.error || `Failed to persist UI state (${response.status})`));
+        }
+        return { skipped: false, response, payload };
+    }
+    catch (error) {
+        remoteUiStatePersistCache.set(persistKey, {
+            serializedPatch,
+            status: 'failure',
+            retryAfter: now + (input.failureRetryMs ?? REMOTE_UI_STATE_FAILURE_RETRY_MS)
+        });
+        logBootstrapDebug('ui_state_persist_failed', {
+            stateKey,
+            workspaceId: workspaceId || 'default',
+            error: error instanceof Error ? error.message : String(error)
+        });
+        if (input.throwOnError)
+            throw error;
+        return { skipped: false, payload: null };
+    }
+}
 function buildWorkspaceContextStorageKey(scopeRaw) {
     const scope = normalizeWorkspaceStorageScope(scopeRaw);
     return `${WORKSPACE_CONTEXT_KEY_PREFIX}.${scope}`;
@@ -71,6 +160,17 @@ export function writePersistedWorkspaceId(workspaceId, scopeRaw) {
         // best-effort only
     }
 }
+export function clearPersistedWorkspaceId(scopeRaw) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.removeItem(buildWorkspaceContextStorageKey(scopeRaw));
+        window.localStorage.removeItem(buildLegacyWorkspaceContextStorageKey(scopeRaw));
+    }
+    catch {
+        // best-effort only
+    }
+}
 function buildAppUiStateStorageKey(scopeRaw) {
     const scope = normalizeWorkspaceStorageScopeLegacy(scopeRaw);
     return `${APP_UI_STATE_STORAGE_KEY_PREFIX}.${scope}`;

package/dist/hooks/workspace/workspaceLocalState.test.d.ts

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

package/dist/hooks/workspace/workspaceLocalState.test.js

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { persistRemoteUiState, resetRemoteUiStatePersistCache } from './workspaceLocalState';
+describe('persistRemoteUiState', () => {
+    afterEach(() => {
+        resetRemoteUiStatePersistCache();
+        vi.unstubAllGlobals();
+        vi.clearAllMocks();
+        vi.useRealTimers();
+    });
+    it('skips identical payloads after a successful persist', async () => {
+        const fetchMock = vi.fn(async () => ({
+            ok: true,
+            status: 200,
+            json: async () => ({ success: true })
+        }));
+        vi.stubGlobal('fetch', fetchMock);
+        const first = await persistRemoteUiState({
+            stateKey: 'app',
+            workspaceId: 'workspace-1',
+            patch: { activeWorkspaceModule: 'tasks' }
+        });
+        const second = await persistRemoteUiState({
+            stateKey: 'app',
+            workspaceId: 'workspace-1',
+            patch: { activeWorkspaceModule: 'tasks' }
+        });
+        expect(first.skipped).toBe(false);
+        expect(second).toEqual({ skipped: true, reason: 'unchanged' });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+    it('backs off identical failed payloads briefly before retrying', async () => {
+        vi.useFakeTimers();
+        const fetchMock = vi.fn(async () => {
+            throw new Error('gateway');
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        const first = await persistRemoteUiState({
+            stateKey: 'layout',
+            workspaceId: 'workspace-1',
+            patch: { planningDrawerOpen: true }
+        });
+        const second = await persistRemoteUiState({
+            stateKey: 'layout',
+            workspaceId: 'workspace-1',
+            patch: { planningDrawerOpen: true }
+        });
+        expect(first.skipped).toBe(false);
+        expect(second).toEqual({ skipped: true, reason: 'cooldown' });
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        vi.advanceTimersByTime(5001);
+        const third = await persistRemoteUiState({
+            stateKey: 'layout',
+            workspaceId: 'workspace-1',
+            patch: { planningDrawerOpen: true }
+        });
+        expect(third.skipped).toBe(false);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+});

package/dist/localization/locales/en-US.js

@@ -118,10 +118,10 @@ export const enUS = {
     setup: {
         headingCheckFailed: 'Setup Check Failed',
         headingGlobalRequired: 'Global Setup Required',
-        headingWorkspaceRequired: 'Workspace Setup Required',
+        headingWorkspaceRequired: 'Configure your new workspace.',
         subtitleUnreadable: 'Taskforce could not read setup state. Retry to continue.',
         subtitleGlobalRequired: 'Choose your default operating mode to continue.',
-        subtitleWorkspaceRequired: 'Set up your workspace profile to continue.',
+        subtitleWorkspaceRequired: '',
         runtimeLabel: 'Runtime',
         workspaceTermProject: 'Project',
         workspaceTermMission: 'Mission',