@taskforcehq/taskforce 0.3.302 → 0.3.304

package/dist/hooks/useTaskforce.js

@@ -39,12 +39,11 @@ import { normalizeTaskFromApi } from '../utils/taskNormalization.js';
 import { getSupportedLocales, initializeLocale } from '../localization';
 import { WORKSPACE_BOOTSTRAP_SCOPE, isReservedWorkspaceId, resolveWorkspaceSelectionScopeForRuntime, resolveWorkspaceUiStateScopeForRuntime } from '../utils/workspaceIdentity';
 import { resolveRuntimeModeContract } from '../shared/runtimeContract';
-import { hasWorkspaceTaxonomyStatePayload, normalizeWorkspaceTaxonomyStatePayload } from '../shared/taxonomyState.js';
 import { DEFAULT_TYPE_VALUE } from '../shared/taxonomyDefaults.js';
 import { cloneDefaultWorkflowDefinitions } from '../shared/workflowDefaults.js';
 import { resolveClientDeploymentConfig } from '../config/clientDeployment';
 import { resolveTaskforceMcpBaseUrlFromBaseUrl } from '../config/cloudEnvironment';
-import { createDefaultAssigneeOptions, createWorkspaceAssigneeOptions, mergeAssigneeOptions } from '../utils/assignees';
+import { createDefaultAssigneeOptions } from '../utils/assignees';
 import { persistLocalMutationActorUserId, readLocalMutationActorUserId } from '../utils/taskforceApiClient';
 import { useSyncOrchestrator } from './useSyncOrchestrator';
 import { useRealtimeSync } from './useRealtimeSync';
@@ -62,9 +61,12 @@ import { useTaskFilters } from './tasks/useTaskFilters';
 import { useTaskFormActions } from './tasks/useTaskFormActions';
 import { useTaskRelationships } from './tasks/useTaskRelationships';
 import { useTaskActions } from './tasks/useTaskActions';
-import { logBootstrapDebug, readPersistedAppUiState, readPersistedWorkspaceId, writePersistedAppUiState, writePersistedWorkspaceId } from './workspace/workspaceLocalState';
+import { clearPersistedWorkspaceId, logBootstrapDebug, persistRemoteUiState, readPersistedAppUiState, readPersistedWorkspaceId, writePersistedAppUiState, writePersistedWorkspaceId } from './workspace/workspaceLocalState';
 import { useTaskforceApiRouting } from './workspace/useTaskforceApiRouting';
-import { deriveAuthGuardPolicy, shouldSkipDataVersionPolling, shouldSkipDataVersionTick } from './auth/useAuthGuardPolicy';
+import { useTaskforceAuthBootstrap } from './auth/useTaskforceAuthBootstrap';
+import { deriveAuthGuardPolicy } from './auth/useAuthGuardPolicy';
+import { useTaskforceWorkspaceBootstrap } from './workspace/useTaskforceWorkspaceBootstrap';
+import { useDataVersionRefresh } from './sync/useDataVersionRefresh';
 const ENV_DEPLOYMENT = resolveClientDeploymentConfig(import.meta.env);
 const DEFAULT_CLOUD_APP_ORIGIN = (() => {
     const configuredBase = ENV_DEPLOYMENT.baseUrl;
@@ -203,7 +205,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         || envCloudBaseUrl
         || normalizedCloudAuthBaseUrl
         || defaultCloudAuthBaseUrl).trim().replace(/\/+$/, '');
-    const authOnlyCloudMode = Boolean(normalizedCloudAuthBaseUrl) && !normalizedApiBaseUrl;
+    const authOnlyCloudMode = !isCloudHost && Boolean(normalizedCloudAuthBaseUrl) && !normalizedApiBaseUrl;
     const shouldProbeCloudAuth = runtimeConfigReady && (Boolean(normalizedCloudAuthBaseUrl || normalizedApiBaseUrl) || isCloudHost);
     const shouldGateProtectedApiCalls = shouldProbeCloudAuth && !authOnlyCloudMode;
     const cloudAuthConfigured = Boolean(normalizedCloudAuthBaseUrl || normalizedApiBaseUrl || isCloudHost);
@@ -229,6 +231,8 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         if (!path.startsWith('/'))
             return path;
         const isCloudScopedPath = path.startsWith('/api/taskforce/auth/')
+            || path.startsWith('/api/taskforce/account/')
+            || path.startsWith('/api/taskforce/billing/')
             || path.startsWith('/api/taskforce/sync/')
             || path.startsWith('/api/taskforce/settings/mcp/');
         if (!isCloudHost && isCloudScopedPath && (!runtimeConfigReady || runtimeConfigOverride.cloudAuthViaLocalProxy)) {
@@ -343,6 +347,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     const [bootstrapError, setBootstrapError] = useState(null);
     const [bootstrapStartedAt, setBootstrapStartedAt] = useState(null);
     const authSessionRequestRef = useRef(null);
+    const authSessionEpochRef = useRef(0);
     const authSessionLastCheckedAtRef = useRef(0);
     const authSessionLastResultRef = useRef(hasOptimisticLocalAuth);
     const currentWorkspaceIdRef = useRef(currentWorkspaceId);
@@ -373,25 +378,16 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     useEffect(() => {
         currentWorkspaceIdRef.current = currentWorkspaceId;
     }, [currentWorkspaceId]);
-    const applyResolvedWorkspaceId = useCallback((nextWorkspaceIdRaw, options) => {
+    const applyResolvedWorkspaceId = useCallback((nextWorkspaceIdRaw) => {
         const nextWorkspaceId = String(nextWorkspaceIdRaw || '').trim();
         if (!nextWorkspaceId)
             return;
-        setCurrentWorkspaceId((prev) => {
+        setCurrentWorkspaceId(() => {
             const explicitWorkspaceId = String(explicitWorkspaceSelectionRef.current || '').trim();
             let resolvedWorkspaceId = nextWorkspaceId;
             if (explicitWorkspaceId && explicitWorkspaceId !== nextWorkspaceId) {
                 resolvedWorkspaceId = explicitWorkspaceId;
             }
-            else {
-                const prevValue = String(prev || '').trim();
-                if (options?.preserveNonDefaultDefault
-                    && nextWorkspaceId === 'default'
-                    && prevValue
-                    && prevValue.toLowerCase() !== 'default') {
-                    resolvedWorkspaceId = prevValue;
-                }
-            }
             currentWorkspaceIdRef.current = resolvedWorkspaceId;
             return resolvedWorkspaceId;
         });
@@ -475,7 +471,11 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         shouldBlockProtectedApiCalls
     });
     const { zenMode, setZenModeState, toggleZenMode } = useZenMode();
-    const { exportEnvironment, setExportEnvironment, availableEnvironments, loadAvailableEnvironments, exportWorkflowsPath, setExportWorkflowsPath, exportingResource, exportResult, handleExportWorkflows } = useResourceExport({ storagePath });
+    const { exportEnvironment, setExportEnvironment, availableEnvironments, loadAvailableEnvironments, exportWorkflowsPath, setExportWorkflowsPath, exportingResource, exportResult, handleExportWorkflows } = useResourceExport({
+        storagePath,
+        shouldDeferProtectedApiCalls,
+        shouldBlockProtectedApiCalls
+    });
     // Unsaved Changes Modal State
     const [unsavedModalOpen, setUnsavedModalOpen] = useState(false);
     const [pendingNavigation, setPendingNavigation] = useState(null);
@@ -811,158 +811,10 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         await fetchDeletedTasks(true);
         await fetchPlanningEntities();
     }, [fetchDeletedTasks, fetchPlanningEntities, refreshTaskCollectionsFromInvalidationBase]);
-    const checkAuthSession = useCallback(async (options) => {
-        const force = options?.force === true;
-        markBootstrapPhase('auth');
-        if (!runtimeConfigReady) {
-            // Keep prior auth identity during bootstrap until runtime auth config is resolved.
-            // This avoids transient "signed out" UI flicker on refresh.
-            return authSessionLastResultRef.current;
-        }
-        if (!shouldProbeCloudAuth) {
-            setRuntimeMode('local');
-            setAuthRequiredForApi(false);
-            setIsAuthenticated(false);
-            setAuthUserId('anonymous');
-            setAuthWorkspaceId('');
-            persistLocalMutationActorUserId(null);
-            setAuthUserEmail('');
-            setAuthUserDisplayName('');
-            setAuthUserAvatarUrl('');
-            setUserGlobalSyncStatus('disconnected');
-            setUserGlobalSyncError(null);
-            setHasBetaAccess(true);
-            setAvailableWorkspaces([]);
-            setHydratedWorkspaceRole(null);
-            setAssigneeOptions(createDefaultAssigneeOptions());
-            setAuthBlocked(false);
-            setAuthSessionResolved(true);
-            authSessionLastResultRef.current = false;
-            authSessionLastCheckedAtRef.current = Date.now();
-            return false;
-        }
-        const sessionUrl = resolveCloudAuthUrl('/api/taskforce/auth/session');
-        const now = Date.now();
-        if (!force && authSessionRequestRef.current)
-            return authSessionRequestRef.current;
-        if (!force && authSessionResolved && (now - authSessionLastCheckedAtRef.current) < 1500) {
-            return authSessionLastResultRef.current;
-        }
-        const request = (async () => {
-            const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now();
-            const abortController = new AbortController();
-            const timeoutId = typeof window !== 'undefined'
-                ? window.setTimeout(() => abortController.abort(), 8000)
-                : null;
-            try {
-                const res = await fetch(sessionUrl, {
-                    method: 'GET',
-                    credentials: 'include',
-                    mode: 'cors',
-                    signal: abortController.signal
-                });
-                if (res.status === 429) {
-                    setAuthSessionResolved(true);
-                    return authSessionLastResultRef.current;
-                }
-                if (!res.ok) {
-                    if (isLoopbackHost)
-                        persistLocalMutationActorUserId(null);
-                    setAuthSessionResolved(true);
-                    authSessionLastResultRef.current = false;
-                    return false;
-                }
-                const data = await res.json();
-                const required = Boolean(data.authRequiredForApi);
-                const authenticated = Boolean(data.authenticated);
-                const betaAccess = authenticated ? (data.betaAccess !== false) : true;
-                const workspaceId = typeof data.workspaceId === 'string' && data.workspaceId.trim().length > 0
-                    ? data.workspaceId.trim()
-                    : '';
-                const userId = typeof data.userId === 'string' && data.userId.trim().length > 0
-                    ? data.userId.trim()
-                    : 'anonymous';
-                const userEmail = typeof data.email === 'string' && data.email.trim().length > 0
-                    ? data.email.trim().toLowerCase()
-                    : '';
-                const userDisplayName = typeof data.displayName === 'string'
-                    ? data.displayName.trim()
-                    : '';
-                const userAvatarUrl = typeof data.avatarUrl === 'string'
-                    ? data.avatarUrl.trim()
-                    : '';
-                const isLocalRuntime = runtimeMode === 'local';
-                const keepLocalWorkspaceContext = runtimeMode === 'local' || authOnlyCloudMode;
-                setAuthRequiredForApi(authOnlyCloudMode ? false : (isLocalRuntime ? false : required));
-                setIsAuthenticated(authenticated);
-                setAuthUserId(authenticated ? userId : 'anonymous');
-                setAuthWorkspaceId(authenticated ? workspaceId : '');
-                if (isLoopbackHost) {
-                    persistLocalMutationActorUserId(authenticated ? userId : null);
-                }
-                setAuthUserEmail(authenticated ? userEmail : '');
-                setAuthUserDisplayName(authenticated ? userDisplayName : '');
-                setAuthUserAvatarUrl(authenticated ? userAvatarUrl : '');
-                if (authenticated) {
-                    setError((prev) => prev === AUTH_REQUIRED_ERROR ? '' : prev);
-                }
-                setUserGlobalSyncStatus(authenticated ? 'idle' : 'disconnected');
-                setUserGlobalSyncError(null);
-                setHasBetaAccess(betaAccess);
-                if (keepLocalWorkspaceContext) {
-                    // Local runtime resolves workspace identity from local DB via /api/taskforce/config.
-                    // Do not override it from cloud auth session payloads.
-                }
-                else {
-                    applyResolvedWorkspaceId(workspaceId || readPersistedWorkspaceId(workspaceSelectionScope) || 'default');
-                }
-                setAuthBlocked(authOnlyCloudMode ? false : (isLocalRuntime ? false : (required && !authenticated)));
-                // Runtime mode should be sourced from /api/taskforce/config, not
-                // from auth-session responses which may come from a separate cloud-auth origin.
-                setAuthSessionResolved(true);
-                authSessionLastResultRef.current = authenticated;
-                logBootstrapDebug('auth_session_resolved', {
-                    authenticated,
-                    durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt)
-                });
-                if (authenticated)
-                    markBootstrapPhase('ready');
-                return authenticated;
-            }
-            catch {
-                if (isLoopbackHost)
-                    persistLocalMutationActorUserId(null);
-                setAuthSessionResolved(true);
-                authSessionLastResultRef.current = false;
-                logBootstrapDebug('auth_session_failed', {
-                    durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt)
-                });
-                markBootstrapStalled('Unable to verify your session.');
-                return authSessionLastResultRef.current;
-            }
-            finally {
-                if (timeoutId !== null && typeof window !== 'undefined') {
-                    window.clearTimeout(timeoutId);
-                }
-                authSessionLastCheckedAtRef.current = Date.now();
-                authSessionRequestRef.current = null;
-            }
-        })();
-        authSessionRequestRef.current = request;
-        return request;
-    }, [
-        runtimeConfigReady,
-        shouldProbeCloudAuth,
-        authSessionResolved,
-        resolveCloudAuthUrl,
-        authOnlyCloudMode,
-        AUTH_REQUIRED_ERROR,
-        runtimeMode,
-        applyResolvedWorkspaceId,
-        workspaceSelectionScope,
-        markBootstrapPhase,
-        markBootstrapStalled
-    ]);
+    const setUserGlobalSyncStatusRef = useRef(() => undefined);
+    const setUserGlobalSyncErrorRef = useRef(() => undefined);
+    const checkAuthSessionImplRef = useRef(async () => false);
+    const checkAuthSession = useCallback((options) => checkAuthSessionImplRef.current(options), []);
     const { userGlobalSyncStatus, setUserGlobalSyncStatus, userGlobalSyncError, setUserGlobalSyncError, workspaceLastPullAt, workspaceLastPushAt, workspaceLastErrorAt, workspaceLastErrorMessage, workspaceLastSuccessfulSyncAt, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceSyncStatus, workspaceSyncSummary, workspaceSyncRecommendedAction, workspaceSyncBusy, workspaceSyncPendingChanges, workspacePushInFlightRef, workspacePullInFlightRef, workspaceLastPushedSignatureRef, workspacePendingSignatureRef, workspaceLastPushedTaskIdsRef, workspaceDeletedTaskIdsRef, workspacePullCursorRef, clearWorkspaceRetry, persistWorkspaceSyncPatch, loadWorkspaceSyncState, applyWorkspaceSyncStateSnapshot, syncUserGlobalSettings, buildWorkspaceSyncSignature, pushWorkspaceChangesToCloud, saveWorkspaceCloudSyncSettings, retryUserGlobalSettingsSync, retryWorkspaceCloudSync, resetWorkspaceSyncCursorAndPull, getWorkspaceSyncDiagnostics } = useSyncOrchestrator({
         currentWorkspaceId,
         cloudAuthConfigured,
@@ -1044,6 +896,50 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         assigneeOptionsLoaded,
         assigneeOptions
     });
+    setUserGlobalSyncStatusRef.current = setUserGlobalSyncStatus;
+    setUserGlobalSyncErrorRef.current = setUserGlobalSyncError;
+    const { checkAuthSession: checkAuthSessionImpl } = useTaskforceAuthBootstrap({
+        runtimeConfigReady,
+        shouldProbeCloudAuth,
+        authSessionResolved,
+        resolveCloudAuthUrl,
+        authOnlyCloudMode,
+        authRequiredError: AUTH_REQUIRED_ERROR,
+        runtimeMode,
+        workspaceSelectionScope,
+        markBootstrapPhase,
+        markBootstrapStalled,
+        setRuntimeMode,
+        setAuthRequiredForApi,
+        setIsAuthenticated,
+        setAuthUserId,
+        setAuthWorkspaceId,
+        setAuthUserEmail,
+        setAuthUserDisplayName,
+        setAuthUserAvatarUrl,
+        setUserGlobalSyncStatus: (value) => setUserGlobalSyncStatusRef.current(value),
+        setUserGlobalSyncError: (value) => setUserGlobalSyncErrorRef.current(value),
+        setHasBetaAccess,
+        setAvailableWorkspaces,
+        setHydratedWorkspaceRole,
+        setAssigneeOptions,
+        setAuthBlocked,
+        setAuthSessionResolved,
+        setError,
+        applyResolvedWorkspaceId,
+        readPersistedWorkspaceId,
+        authSessionRequestRef,
+        authSessionEpochRef,
+        authSessionLastCheckedAtRef,
+        authSessionLastResultRef,
+        isLoopbackHost,
+        setAuthStateReadyRefs: (authenticated, resolved, required) => {
+            authSessionResolvedRef.current = resolved;
+            authRequiredForApiRef.current = required;
+            isAuthenticatedRef.current = authenticated;
+        }
+    });
+    checkAuthSessionImplRef.current = checkAuthSessionImpl;
     const [activeWorkspaceModule, setActiveWorkspaceModule] = useState('tasks');
     const [showComments, setShowComments] = useState(false);
     const [descriptionFocused, setDescriptionFocused] = useState(false);
@@ -1067,6 +963,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     const skipNextUiStatePersistRef = useRef(false);
     const referenceDataRequestRef = useRef(null);
     const workspaceListHydratedRef = useRef(false);
+    const hasBootstrappedDataRef = useRef(false);
     const [uiStateReady, setUiStateReady] = useState(false);
     const { handleSaveSettings, handleSaveTheme, handleSaveGlobalTheme, handleJsonBackupEnabledChange, handleSaveGlobalJsonBackupEnabled, handleSaveGlobalWeekStartsOn, handleSaveLocale, handleManualComplexityEnabledChange, handleChecklistDropdownEnabledChange, handleShowTaskCardStatusLabelChange, handleResetProjectToGlobal } = useSettingsPersistence({
         keyShortcut,
@@ -1234,15 +1131,10 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         writePersistedAppUiState(uiStateSnapshot, workspaceUiStateScope);
         const timeoutId = window.setTimeout(async () => {
             try {
-                await fetch('/api/taskforce/ui-state', {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    credentials: 'include',
-                    body: JSON.stringify({
-                        stateKey: 'app',
-                        workspaceId: currentWorkspaceIdRef.current,
-                        patch: uiStateSnapshot
-                    })
+                await persistRemoteUiState({
+                    stateKey: 'app',
+                    workspaceId: currentWorkspaceIdRef.current,
+                    patch: uiStateSnapshot
                 });
             }
             catch {
@@ -1279,13 +1171,15 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             ? data.userId.trim()
             : 'anonymous';
         const serverAuthenticated = nextRuntimeMode === 'cloud' && nextUserId !== 'anonymous';
+        const knownAuthenticated = serverAuthenticated || isAuthenticatedRef.current;
+        const authResolved = authSessionResolvedRef.current;
         setRuntimeMode(nextRuntimeMode);
         setAuthRequiredForApi(nextAuthRequiredForApi);
         if (serverAuthenticated) {
             setIsAuthenticated(true);
             setAuthUserId(nextUserId);
             setAuthBlocked(false);
-            if (!authSessionResolved) {
+            if (!authResolved) {
                 setAuthSessionResolved(true);
             }
         }
@@ -1295,11 +1189,11 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 commitCurrentWorkspaceId(nextWorkspaceId);
             }
             else {
-                applyResolvedWorkspaceId(nextWorkspaceId, { preserveNonDefaultDefault: true });
+                applyResolvedWorkspaceId(nextWorkspaceId);
             }
         }
         if (nextRuntimeMode === 'cloud' && nextAuthRequiredForApi) {
-            setAuthBlocked(!(serverAuthenticated || isAuthenticated));
+            setAuthBlocked(!knownAuthenticated);
         }
         else {
             setAuthBlocked(false);
@@ -1397,7 +1291,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         else {
             setShowTaskCardStatusLabel(true);
         }
-    }, [applyResolvedWorkspaceId, authSessionResolved, commitCurrentWorkspaceId, isAuthenticated]);
+    }, [applyResolvedWorkspaceId, commitCurrentWorkspaceId]);
     const fetchBuildInfo = useCallback(async () => {
         const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now();
         try {
@@ -1423,417 +1317,83 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             }
         }
     }, [fetchWithTimeout, isBootstrapTimeoutError, markBootstrapStalled]);
-    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 () => {
-            const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now();
-            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(() => ({}));
-                    const hasUnifiedPayload = hasWorkspaceTaxonomyStatePayload(taxonomyData);
-                    if (!hasUnifiedPayload) {
-                        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 normalizedTaxonomyState = normalizeWorkspaceTaxonomyStatePayload(taxonomyData);
-                    if (isWorkspaceRequestStale(requestState))
-                        return;
-                    if (normalizedTaxonomyState.categories.length > 0)
-                        setCustomCategories(normalizedTaxonomyState.categories);
-                    if (normalizedTaxonomyState.types.length > 0)
-                        setCustomTypes(normalizedTaxonomyState.types);
-                    if (normalizedTaxonomyState.priorities.length > 0)
-                        setPriorities(normalizedTaxonomyState.priorities);
-                    setTaxonomies(normalizedTaxonomyState.taxonomies);
-                    setTaxonomyDisplayLabels(normalizedTaxonomyState.displayLabels || {});
-                })(),
-                (async () => {
-                    await fetchWorkflows();
-                })(),
-                (async () => {
-                    await fetchInitiativeTemplates();
-                })(),
-                (async () => {
-                    await loadAvailableEnvironments();
-                })(),
-            ]);
-            if (isWorkspaceRequestStale(requestState))
-                return;
-            setReferenceDataLoaded(true);
-            logBootstrapDebug('reference_data_loaded', {
-                durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt)
-            });
-        })();
-        referenceDataRequestRef.current = { workspaceId: requestState.workspaceId, promise: request };
-        try {
-            await request;
-        }
-        catch (error) {
-            if (!isAbortError(error))
-                throw error;
-        }
-        finally {
-            if (referenceDataRequestRef.current?.promise === request) {
-                referenceDataRequestRef.current = null;
-            }
-            if (referenceDataAbortRef.current === abortController) {
-                referenceDataAbortRef.current = null;
-            }
-        }
-    }, [
-        fetchWorkflows,
-        fetchInitiativeTemplates,
-        getWorkspaceRequestState,
-        isAbortError,
-        isWorkspaceRequestStale,
-        loadAvailableEnvironments,
+    const { fetchReferenceData, fetchBootstrapConfig, fetchConfig, fetchWorkspaces, fetchAssigneeOptions, switchWorkspace, resolveWorkspaceAfterAuth, retryBootstrapChecks } = useTaskforceWorkspaceBootstrap({
         shouldDeferProtectedApiCalls,
-        shouldBlockProtectedApiCalls
-    ]);
-    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;
-        const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now();
-        try {
-            const res = await fetchWithTimeout('/api/taskforce/config', undefined, BOOTSTRAP_REQUEST_TIMEOUT_MS, {
-                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) {
-                const uiStateWorkspaceId = configResolvedWorkspaceId || requestState.workspaceId;
-                hasLoadedUiStateRef.current = true;
-                await loadPersistedUiState(uiStateWorkspaceId);
-            }
-            if (isWorkspaceEpochStale(requestState)) {
-                const liveWorkspaceId = String(currentWorkspaceIdRef.current || 'default').trim() || 'default';
-                if (!configResolvedWorkspaceId || liveWorkspaceId !== configResolvedWorkspaceId) {
-                    return;
-                }
-            }
-            setConfigLoaded(true);
-            markBootstrapPhase('ready');
-            logBootstrapDebug('bootstrap_config_loaded', {
-                durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt)
-            });
-            void fetchBuildInfo();
-        }
-        catch (error) {
-            if (isAbortError(error))
-                return;
-            if (isWorkspaceEpochStale(requestState))
-                return;
-            if (!hasLoadedUiStateRef.current) {
-                hasLoadedUiStateRef.current = true;
-                await loadPersistedUiState(requestState.workspaceId);
-            }
-            if (isBootstrapTimeoutError(error)) {
-                markBootstrapStalled('Startup checks timed out.');
-            }
-            else {
-                markBootstrapStalled('Unable to finish startup checks.');
-            }
-            setConfigLoaded(true);
-        }
-        finally {
-            if (bootstrapConfigAbortRef.current === abortController) {
-                bootstrapConfigAbortRef.current = null;
-            }
-        }
-    }, [
-        applyBootstrapConfig,
-        fetchBuildInfo,
-        fetchWithTimeout,
+        shouldBlockProtectedApiCalls,
         getWorkspaceRequestState,
-        handleUnauthorized,
+        isWorkspaceRequestStale,
+        isWorkspaceEpochStale,
         isAbortError,
         isBootstrapTimeoutError,
-        isWorkspaceEpochStale,
-        isWorkspaceRequestStale,
+        fetchWithTimeout,
+        handleUnauthorized,
+        applyBootstrapConfig,
         loadPersistedUiState,
+        fetchBuildInfo,
         markBootstrapPhase,
         markBootstrapStalled,
-        shouldDeferProtectedApiCalls,
-        shouldBlockProtectedApiCalls
-    ]);
-    const fetchConfig = useCallback(async (options) => {
-        await fetchBootstrapConfig(options);
-        await fetchReferenceData(options);
-    }, [fetchBootstrapConfig, fetchReferenceData]);
+        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: (workspaceId, options) => {
+            explicitWorkspaceSelectionRef.current = workspaceId;
+            commitCurrentWorkspaceId(workspaceId, options);
+            if (options?.clearExplicitSelection !== false) {
+                explicitWorkspaceSelectionRef.current = null;
+            }
+        },
+        currentWorkspaceId,
+        workspaceSelectionScope,
+        abortWorkspaceScopedRequests,
+        setWorkspaceBootstrapPending,
+        checkAuthSession,
+        lastConfigRefreshKeyRef,
+        lastAssigneeOptionsLoadKeyRef,
+        lastWorkspaceSyncStateLoadKeyRef,
+        lastTaskSurfaceLoadKeyRef,
+        lastSettingsSurfaceLoadKeyRef,
+        isOpen,
+        activeTab,
+        showArchive,
+        taskScope,
+        settingsSection,
+        fetchTasks,
+        fetchArchive,
+        fetchPlanningEntities,
+        refreshTaskCollections,
+        loadWorkspaceSyncState,
+        archiveBootstrapTimerRef,
+        hasBootstrappedDataRef
+    });
     const refreshSetupContext = useCallback(async () => {
         await checkAuthSession();
         await fetchConfig();
     }, [checkAuthSession, fetchConfig]);
-    const fetchWorkspaces = useCallback(async () => {
-        if (!workspaceSwitchingEnabled) {
-            setAvailableWorkspaces([]);
-            workspaceListHydratedRef.current = false;
-            return { success: true, workspaces: [] };
-        }
-        const requestState = getWorkspaceRequestState();
-        const abortController = new AbortController();
-        workspaceListAbortRef.current = abortController;
-        const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now();
-        try {
-            const res = await fetchWithTimeout('/api/taskforce/workspaces', {
-                method: 'GET',
-                credentials: 'include'
-            }, BOOTSTRAP_REQUEST_TIMEOUT_MS, {
-                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 : [];
-            setAvailableWorkspaces(workspaces);
-            workspaceListHydratedRef.current = true;
-            if (runtimeMode !== 'local' && typeof data?.currentWorkspaceId === 'string' && data.currentWorkspaceId.trim().length > 0) {
-                applyResolvedWorkspaceId(data.currentWorkspaceId.trim(), { preserveNonDefaultDefault: true });
-            }
-            logBootstrapDebug('workspace_list_loaded', {
-                workspaceCount: workspaces.length,
-                durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt)
-            });
-            return { success: true, workspaces };
-        }
-        catch (error) {
-            if (isAbortError(error)) {
-                return { success: false, error: 'Workspace list request aborted.' };
-            }
-            if (isBootstrapTimeoutError(error)) {
-                markBootstrapStalled('Startup checks timed out.');
-            }
-            setAvailableWorkspaces([]);
-            workspaceListHydratedRef.current = false;
-            return { success: false, error: 'Failed to load workspaces.' };
-        }
-        finally {
-            if (workspaceListAbortRef.current === abortController) {
-                workspaceListAbortRef.current = null;
-            }
-        }
-    }, [
-        applyResolvedWorkspaceId,
-        fetchWithTimeout,
-        getWorkspaceRequestState,
-        isAbortError,
-        isWorkspaceEpochStale,
-        isBootstrapTimeoutError,
-        isWorkspaceRequestStale,
-        markBootstrapStalled,
-        runtimeMode,
-        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'
-                }, BOOTSTRAP_REQUEST_TIMEOUT_MS, {
-                    signal: abortController.signal
-                }),
-                (authSessionResolved && isAuthenticated)
-                    ? fetchWithTimeout('/api/taskforce/auth/workspace-members', {
-                        method: 'GET',
-                        credentials: 'include'
-                    }, BOOTSTRAP_REQUEST_TIMEOUT_MS, {
-                        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((candidate) => Boolean(candidate));
-            const fallbackCandidates = assignees
-                .map((candidate) => ({
-                userId: String(candidate?.userId || '').trim(),
-                email: String(candidate?.email || '').trim().toLowerCase(),
-                displayName: typeof candidate?.displayName === 'string' ? candidate.displayName : null,
-                status: typeof candidate?.status === 'string' ? candidate.status : null,
-                disabled: candidate?.disabled === true,
-            }))
-                .filter((candidate) => candidate.userId
-                && String(candidate.status || 'active').trim().toLowerCase() === 'active'
-                && candidate.disabled !== true);
-            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,
-                    status: typeof candidate?.status === 'string' ? candidate.status : null,
-                    disabled: candidate?.disabled === true,
-                }))
-                    .filter((candidate) => candidate.userId
-                    && String(candidate.status || 'active').trim().toLowerCase() === 'active'
-                    && candidate.disabled !== true)
-                    .map((candidate) => ({
-                    userId: candidate.userId,
-                    email: candidate.email,
-                    displayName: candidate.displayName ?? null
-                }));
-                memberCandidates = Array.from(new Map([...fallbackCandidates, ...workspaceMemberCandidates].map((candidate) => [
-                    String(candidate.userId || '').trim(),
-                    candidate
-                ])).values()).filter((candidate) => String(candidate.userId || '').trim().length > 0);
-            }
-            else if (!workspaceSwitchingEnabled && !fallbackCandidates.length) {
-                setHydratedWorkspaceRole(null);
-            }
-            const mergedOptions = mergeAssigneeOptions([
-                ...directOptions,
-                ...createWorkspaceAssigneeOptions(memberCandidates).filter((option) => option.kind === 'member')
-            ]);
-            if (isWorkspaceRequestStale(requestState)) {
-                return { success: false, error: 'Workspace changed while loading assignee options.' };
-            }
-            setAssigneeOptions(mergedOptions);
-            setAssigneeOptionsLoaded(true);
-            return { success: true };
-        }
-        catch (error) {
-            if (isAbortError(error)) {
-                return { success: false, error: 'Assignee options request aborted.' };
-            }
-            if (!isWorkspaceRequestStale(requestState)) {
-                setAssigneeOptions(createDefaultAssigneeOptions());
-                setAssigneeOptionsLoaded(true);
-            }
-            return { success: false, error: 'Failed to load assignee options.' };
-        }
-        finally {
-            if (assigneeOptionsAbortRef.current === abortController) {
-                assigneeOptionsAbortRef.current = null;
-            }
-        }
-    }, [authSessionResolved, authUserId, fetchWithTimeout, getWorkspaceRequestState, isAbortError, isAuthenticated, isWorkspaceRequestStale, workspaceSwitchingEnabled]);
     useEffect(() => {
         if (!configLoaded || workspaceBootstrapPending)
             return;
@@ -1855,162 +1415,44 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             setHydratedWorkspaceRole(null);
         }
     }, [isAuthenticated]);
-    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 };
-            }
-            explicitWorkspaceSelectionRef.current = normalizedWorkspaceId;
-            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()
-                ]);
-            }
-            if (explicitWorkspaceSelectionRef.current === normalizedWorkspaceId) {
-                explicitWorkspaceSelectionRef.current = null;
-            }
-            return { success: true };
-        }
-        catch {
-            if (explicitWorkspaceSelectionRef.current === normalizedWorkspaceId) {
-                explicitWorkspaceSelectionRef.current = null;
-            }
-            return { success: false, error: 'Failed to switch workspace.' };
-        }
-        finally {
-            setWorkspaceBootstrapPending(false);
+    const continueAfterCommercialOnboarding = useCallback(async () => {
+        setBootstrapError(null);
+        markBootstrapPhase('auth');
+        const authenticated = await checkAuthSession({ force: true });
+        if (!authenticated) {
+            await fetchConfig({ ignoreAuthGuard: true });
+            return { success: false, destination: 'login', error: 'Sign in required.', code: 'AUTH_REQUIRED' };
         }
-    }, [abortWorkspaceScopedRequests, activeTab, checkAuthSession, commitCurrentWorkspaceId, fetchAssigneeOptions, fetchConfig, fetchWorkspaces, isOpen, loadWorkspaceSyncState, markBootstrapPhase, refreshTaskCollections, runtimeMode, settingsSection, showArchive, taskScope, workspaceSelectionScope, workspaceSwitchingEnabled]);
-    const resolveWorkspaceAfterAuth = useCallback(async (options) => {
-        markBootstrapPhase('workspace');
-        setWorkspaceBootstrapPending(true);
-        const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now();
-        try {
-            if (!workspaceSwitchingEnabled) {
-                const localWorkspaceId = String(currentWorkspaceId || '').trim() || 'default';
-                commitCurrentWorkspaceId(localWorkspaceId);
-                logBootstrapDebug('workspace_resolved', {
-                    workspaceId: localWorkspaceId,
-                    workspaceSetupRequired: false,
-                    durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt)
-                });
-                return { success: true, workspaceSetupRequired: false, workspaceId: localWorkspaceId };
-            }
-            const preferredWorkspaceId = String(options?.preferredWorkspaceId || '').trim();
-            const persistedWorkspaceId = readPersistedWorkspaceId(workspaceSelectionScope);
-            const workspacesResult = await fetchWorkspaces();
-            if (!workspacesResult.success) {
+        if (workspaceSwitchingEnabled) {
+            const workspaceResolution = await resolveWorkspaceAfterAuth();
+            if (!workspaceResolution.success) {
+                await fetchConfig({ ignoreAuthGuard: true });
                 return {
                     success: false,
-                    workspaceSetupRequired: false,
-                    error: workspacesResult.error || 'Failed to load workspaces after authentication.'
+                    destination: 'app',
+                    error: workspaceResolution.error || 'Unable to resolve workspace after plan selection.',
+                    code: workspaceResolution.code
                 };
             }
-            const workspaces = Array.isArray(workspacesResult.workspaces) ? workspacesResult.workspaces : [];
-            if (workspaces.length === 0) {
-                commitCurrentWorkspaceId('default');
-                logBootstrapDebug('workspace_resolved', {
-                    workspaceId: 'default',
-                    workspaceSetupRequired: true,
-                    durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt)
-                });
-                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);
-            }
-            logBootstrapDebug('workspace_resolved', {
-                workspaceId: selectedWorkspaceId,
-                workspaceSetupRequired: false,
-                durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt)
-            });
-            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,
-        fetchWorkspaces,
-        markBootstrapPhase,
-        markBootstrapStalled,
-        workspaceSelectionScope,
-        switchWorkspace,
-        workspaceSwitchingEnabled
-    ]);
-    const retryBootstrapChecks = useCallback(async () => {
-        setBootstrapError(null);
-        markBootstrapPhase('auth');
-        const authenticated = await checkAuthSession();
-        if (workspaceSwitchingEnabled && authenticated) {
-            const workspaceResolution = await resolveWorkspaceAfterAuth();
-            if (!workspaceResolution.success || workspaceResolution.workspaceSetupRequired) {
+            if (workspaceResolution.workspaceSetupRequired) {
                 await fetchConfig({ ignoreAuthGuard: true });
-                return;
+                return { success: true, destination: 'setup' };
             }
         }
-        await fetchConfig({ ignoreAuthGuard: true });
+        await fetchBootstrapConfig();
+        await Promise.all([
+            fetchTasks(true, { ignoreAuthGuard: true }),
+            fetchReferenceData(),
+            fetchPlanningEntities()
+        ]);
+        return { success: true, destination: 'app' };
     }, [
         checkAuthSession,
+        fetchBootstrapConfig,
         fetchConfig,
+        fetchPlanningEntities,
+        fetchReferenceData,
+        fetchTasks,
         markBootstrapPhase,
         resolveWorkspaceAfterAuth,
         workspaceSwitchingEnabled
@@ -2066,7 +1508,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             if (!res.ok || data?.success === false) {
                 return { success: false, error: data?.error || `Failed to delete workspace (${res.status})`, code: data?.code };
             }
-            await checkAuthSession();
+            await checkAuthSession({ force: true });
             await Promise.all([fetchConfig(), fetchWorkspaces()]);
             const nextWorkspaceId = typeof data?.nextWorkspaceId === 'string' ? data.nextWorkspaceId.trim() : '';
             if (nextWorkspaceId) {
@@ -2104,6 +1546,9 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     }, [refreshSetupContext]);
     const saveWorkspaceProfile = useCallback(async (input) => {
         const name = String(input?.name || '').trim();
+        const requestedWorkspaceId = typeof input?.workspaceId === 'string'
+            ? input.workspaceId.trim()
+            : '';
         if (!name)
             return { success: false, error: 'Workspace name is required.', code: 'WORKSPACE_NAME_REQUIRED' };
         try {
@@ -2115,7 +1560,9 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 },
                 credentials: 'include',
                 body: JSON.stringify({
-                    workspaceId: input.workspaceId,
+                    workspaceId: requestedWorkspaceId && requestedWorkspaceId !== 'default'
+                        ? requestedWorkspaceId
+                        : undefined,
                     name,
                     description: typeof input.description === 'string' ? input.description : undefined,
                     allowCreate: true
@@ -2168,7 +1615,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 return { success: false, error: data?.error || 'Sign in failed.', code: data?.code };
             }
             setError('');
-            await checkAuthSession();
+            await checkAuthSession({ force: true });
             const workspaceResolution = await resolveWorkspaceAfterAuth();
             if (!workspaceResolution.success) {
                 return {
@@ -2178,6 +1625,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 };
             }
             if (workspaceResolution.workspaceSetupRequired) {
+                await fetchConfig({ ignoreAuthGuard: true });
                 return { success: true, workspaceSetupRequired: true };
             }
             await Promise.all([
@@ -2224,12 +1672,64 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             });
             const data = await res.json().catch(() => ({}));
             if (!res.ok || !data?.success) {
-                return { success: false, error: data?.error || 'Create account failed.', code: data?.code };
+                return {
+                    success: false,
+                    error: data?.error || 'Create account failed.',
+                    code: data?.code,
+                    verificationRequired: Boolean(data?.verificationRequired),
+                    verificationToken: typeof data?.verificationToken === 'string' ? data.verificationToken : undefined,
+                    emailSent: data?.emailSent !== false,
+                    emailError: typeof data?.emailError === 'string' ? data.emailError : undefined
+                };
+            }
+            const planSelectionRequired = data?.planSelectionRequired === true;
+            const checkoutPending = data?.checkoutPending === true;
+            const commercialState = typeof data?.commercialState === 'string' ? data.commercialState : null;
+            const verificationRequired = Boolean(data?.verificationRequired);
+            if (!verificationRequired) {
+                setError('');
+                await checkAuthSession({ force: true });
+                const workspaceResolution = await resolveWorkspaceAfterAuth();
+                if (!workspaceResolution.success) {
+                    return {
+                        success: false,
+                        error: workspaceResolution.error || 'Unable to resolve workspace after registration.',
+                        code: workspaceResolution.code
+                    };
+                }
+                const hasCommercialOnboardingGate = Boolean(planSelectionRequired
+                    || checkoutPending
+                    || commercialState === 'pending_plan_selection'
+                    || commercialState === 'checkout_pending');
+                if (workspaceResolution.workspaceSetupRequired || hasCommercialOnboardingGate) {
+                    await fetchConfig({ ignoreAuthGuard: true });
+                }
+                else {
+                    await Promise.all([
+                        fetchConfig({ ignoreAuthGuard: true }),
+                        fetchTasks(true, { ignoreAuthGuard: true })
+                    ]);
+                    void syncUserGlobalSettings({ preferCloudOnFirstSync: true });
+                }
+                return {
+                    success: true,
+                    workspaceSetupRequired: workspaceResolution.workspaceSetupRequired,
+                    planSelectionRequired,
+                    checkoutPending,
+                    commercialState,
+                    verificationRequired,
+                    verificationToken: typeof data?.verificationToken === 'string' ? data.verificationToken : undefined,
+                    emailSent: data?.emailSent !== false,
+                    emailError: typeof data?.emailError === 'string' ? data.emailError : undefined
+                };
             }
             return {
                 success: true,
                 workspaceSetupRequired: Boolean(data?.workspaceSetupRequired),
-                verificationRequired: Boolean(data?.verificationRequired),
+                planSelectionRequired,
+                checkoutPending,
+                commercialState,
+                verificationRequired,
                 verificationToken: typeof data?.verificationToken === 'string' ? data.verificationToken : undefined,
                 emailSent: data?.emailSent !== false,
                 emailError: typeof data?.emailError === 'string' ? data.emailError : undefined
@@ -2238,7 +1738,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         catch {
             return { success: false, error: 'Create account failed.' };
         }
-    }, [resolveCloudAuthUrl, cloudAuthConfigured]);
+    }, [checkAuthSession, fetchConfig, fetchTasks, resolveWorkspaceAfterAuth, syncUserGlobalSettings, resolveCloudAuthUrl, cloudAuthConfigured]);
     const updateCurrentUserProfile = useCallback(async (input) => {
         if (!cloudAuthConfigured) {
             return { success: false, error: 'Cloud auth endpoint is not configured.' };
@@ -2443,7 +1943,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 return { success: false, error: data?.error || 'Invite acceptance failed.', code: data?.code };
             }
             setError('');
-            await checkAuthSession();
+            await checkAuthSession({ force: true });
             const preferredWorkspaceId = typeof data?.workspaceId === 'string' ? data.workspaceId : null;
             const workspaceResolution = await resolveWorkspaceAfterAuth({ preferredWorkspaceId });
             if (!workspaceResolution.success) {
@@ -2511,6 +2011,34 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             return { success: false, error: 'Invite join failed.' };
         }
     }, [checkAuthSession, fetchConfig, fetchTasks, resolveWorkspaceAfterAuth, syncUserGlobalSettings, resolveCloudAuthUrl, cloudAuthConfigured]);
+    const resetCloudLogoutClientState = useCallback(() => {
+        abortWorkspaceScopedRequests();
+        referenceDataRequestRef.current = null;
+        lastLoadedUiStateKeyRef.current = '';
+        lastAssigneeOptionsLoadKeyRef.current = '';
+        lastConfigRefreshKeyRef.current = '';
+        lastWorkspaceSyncStateLoadKeyRef.current = '';
+        lastTaskSurfaceLoadKeyRef.current = '';
+        lastSettingsSurfaceLoadKeyRef.current = '';
+        setUiStateReady(false);
+        setReferenceDataLoaded(false);
+        setAssigneeOptions(createDefaultAssigneeOptions());
+        setAssigneeOptionsLoaded(false);
+        setDeletedTasks([]);
+        setTasks([]);
+        setArchivedTasks([]);
+        setInitiatives([]);
+        setWorkstreams([]);
+        setLoadingTasks(false);
+        if (cloudRealtimeFollowUpRefreshTimerRef.current !== null && typeof window !== 'undefined') {
+            window.clearTimeout(cloudRealtimeFollowUpRefreshTimerRef.current);
+            cloudRealtimeFollowUpRefreshTimerRef.current = null;
+        }
+        if (archiveBootstrapTimerRef.current !== null && typeof window !== 'undefined') {
+            window.clearTimeout(archiveBootstrapTimerRef.current);
+            archiveBootstrapTimerRef.current = null;
+        }
+    }, [abortWorkspaceScopedRequests, setArchivedTasks, setTasks]);
     const logout = useCallback(async () => {
         try {
             if (cloudAuthConfigured) {
@@ -2524,6 +2052,8 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             // no-op
         }
         finally {
+            abortWorkspaceScopedRequests();
+            authSessionEpochRef.current += 1;
             authSessionRequestRef.current = null;
             authSessionLastResultRef.current = false;
             authSessionLastCheckedAtRef.current = Date.now();
@@ -2538,19 +2068,18 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             setUserGlobalSyncStatus('disconnected');
             setUserGlobalSyncError(null);
             setHasBetaAccess(true);
+            setProjectName('');
+            setConfigLoaded(false);
+            setReferenceDataLoaded(false);
+            setSetupState(null);
+            setBootstrapPhase('idle');
+            setBootstrapError(null);
+            hasLoadedUiStateRef.current = false;
+            if (runtimeMode !== 'local') {
+                clearPersistedWorkspaceId(workspaceSelectionScope);
+            }
             setAuthBlocked(runtimeMode === 'cloud' && authRequiredForApi);
-            setCurrentWorkspaceId((prev) => {
-                const existing = String(prev || '').trim();
-                let resolvedWorkspaceId = 'default';
-                if (existing && existing.toLowerCase() !== 'default') {
-                    resolvedWorkspaceId = existing;
-                }
-                else if (runtimeMode !== 'local') {
-                    resolvedWorkspaceId = readPersistedWorkspaceId(workspaceSelectionScope) || 'default';
-                }
-                currentWorkspaceIdRef.current = resolvedWorkspaceId;
-                return resolvedWorkspaceId;
-            });
+            commitCurrentWorkspaceId('default');
             setAvailableWorkspaces([]);
             workspaceListHydratedRef.current = false;
             setHydratedWorkspaceRole(null);
@@ -2563,12 +2092,14 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 ]);
                 return;
             }
-            setTasks([]);
-            setInitiatives([]);
-            setWorkstreams([]);
+            hasBootstrappedDataRef.current = false;
+            resetCloudLogoutClientState();
         }
     }, [
+        abortWorkspaceScopedRequests,
         authRequiredForApi,
+        clearPersistedWorkspaceId,
+        commitCurrentWorkspaceId,
         resolveCloudAuthUrl,
         cloudAuthConfigured,
         workspaceSelectionScope,
@@ -2576,7 +2107,8 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         fetchConfig,
         fetchPlanningEntities,
         fetchReferenceData,
-        fetchTasks
+        fetchTasks,
+        resetCloudLogoutClientState
     ]);
     const createInitiativeFromTemplate = useCallback(async (payload) => {
         try {
@@ -2694,7 +2226,6 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     }, [fetchPlanningEntities]);
     // Initialize auth once, then bootstrap protected data once auth gates are settled.
     const hasInitializedAuthRef = useRef(false);
-    const hasBootstrappedDataRef = useRef(false);
     useEffect(() => {
         setIsOpen(true); // Always open in standalone-first
         if (hasInitializedAuthRef.current)
@@ -2953,73 +2484,19 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         userId: normalizedRealtimeUserId || undefined
     });
     // Fallback sync for cross-process writes (e.g., MCP tools) that may miss watcher/websocket events.
-    useEffect(() => {
-        if (typeof window === 'undefined' || typeof document === 'undefined')
-            return;
-        if (shouldSkipDataVersionPolling({
-            isOpen,
-            authBlocked,
-            authRequiredForApi,
-            isAuthenticated,
-            canCallProtectedApi: authGuardPolicy.canCallProtectedApi
-        }))
-            return;
-        let cancelled = false;
-        const checkDataVersion = async () => {
-            if (cancelled || document.visibilityState !== 'visible')
-                return;
-            if (shouldSkipDataVersionTick({
-                shouldGateProtectedApiCalls,
-                authSessionResolved: authSessionResolvedRef.current,
-                authRequiredForApi: authRequiredForApiRef.current,
-                isAuthenticated: isAuthenticatedRef.current
-            }))
-                return;
-            try {
-                const res = await fetch('/api/taskforce/data-version');
-                if (!res.ok)
-                    return;
-                const data = await res.json();
-                const version = Number(data?.dataVersion);
-                if (!Number.isFinite(version))
-                    return;
-                if (dataVersionRef.current === null) {
-                    dataVersionRef.current = version;
-                    return;
-                }
-                if (version !== dataVersionRef.current) {
-                    dataVersionRef.current = version;
-                    await refreshTaskCollectionsForDataVersion();
-                }
-            }
-            catch {
-                // Keep polling best-effort and silent.
-            }
-        };
-        const onVisibilityChange = () => {
-            if (document.visibilityState === 'visible') {
-                checkDataVersion();
-            }
-        };
-        const intervalId = window.setInterval(checkDataVersion, 3000);
-        document.addEventListener('visibilitychange', onVisibilityChange);
-        checkDataVersion();
-        return () => {
-            cancelled = true;
-            window.clearInterval(intervalId);
-            document.removeEventListener('visibilitychange', onVisibilityChange);
-        };
-    }, [
+    useDataVersionRefresh({
         isOpen,
-        fetchTasks,
-        fetchArchive,
         authBlocked,
         authRequiredForApi,
         isAuthenticated,
-        authGuardPolicy,
+        canCallProtectedApi: authGuardPolicy.canCallProtectedApi,
         shouldGateProtectedApiCalls,
+        authSessionResolvedRef,
+        authRequiredForApiRef,
+        isAuthenticatedRef,
+        dataVersionRef,
         refreshTaskCollectionsForDataVersion
-    ]);
+    });
     const relationshipTasks = useMemo(() => {
         const byId = new Map();
         for (const task of archivedTasks)
@@ -3543,6 +3020,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         runtimeCapabilities,
         refreshSetupContext,
         retryBootstrapChecks,
+        continueAfterCommercialOnboarding,
         saveWorkspaceProfile,
         fetchWorkspaces,
         createWorkspace,