@taskforcehq/taskforce 0.3.305 → 0.3.306

package/dist/hooks/workspace/useTaskforceWorkspaceBootstrap.js

@@ -2,29 +2,60 @@ import { useCallback, useEffect } from 'react';
 import { createDefaultAssigneeOptions, createWorkspaceAssigneeOptions, mergeAssigneeOptions } from '../../utils/assignees';
 import { hasWorkspaceTaxonomyStatePayload, normalizeWorkspaceTaxonomyStatePayload } from '../../shared/taxonomyState.js';
 import { logBootstrapDebug, readPersistedWorkspaceId } from './workspaceLocalState';
+function getBootstrapTimestamp() {
+    return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
 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 { 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, authUserAvatarUrl, setHydratedWorkspaceRole, setAssigneeOptions, setAssigneeOptionsLoaded, commitCurrentWorkspaceId, currentWorkspaceId, workspaceSelectionScope, abortWorkspaceScopedRequests, setWorkspaceBootstrapPending, checkAuthSession, lastConfigRefreshKeyRef, lastAssigneeOptionsLoadKeyRef, lastWorkspaceSyncStateLoadKeyRef, lastTaskSurfaceLoadKeyRef, lastSettingsSurfaceLoadKeyRef, isOpen, activeTab, showArchive, taskScope, settingsSection, workspaceBootstrapPending, 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))
+        if (!ignoreAuthGuard && (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls)) {
+            logBootstrapDebug('bootstrap_reference_data_skipped', {
+                reason: shouldBlockProtectedApiCalls ? 'auth_blocked' : 'auth_deferred',
+                runtimeMode,
+                workspaceId: String(getWorkspaceRequestState().workspaceId || '').trim() || 'default',
+                force
+            });
             return;
+        }
         const requestState = getWorkspaceRequestState();
+        const normalizedWorkspaceId = String(requestState.workspaceId || '').trim() || 'default';
+        const cloudWorkspaceResolved = runtimeMode !== 'cloud'
+            || !authSessionResolved
+            || !isAuthenticated
+            || (normalizedWorkspaceId !== '' && normalizedWorkspaceId !== 'default');
+        if (!cloudWorkspaceResolved) {
+            logBootstrapDebug('bootstrap_reference_data_skipped', {
+                reason: 'workspace_unresolved',
+                runtimeMode,
+                workspaceId: normalizedWorkspaceId,
+                force
+            });
+            return;
+        }
         if (!force && referenceDataRequestRef.current?.workspaceId === requestState.workspaceId) {
+            logBootstrapDebug('bootstrap_reference_data_reused', {
+                workspaceId: normalizedWorkspaceId,
+                force
+            });
             await referenceDataRequestRef.current.promise;
             return;
         }
         setReferenceDataLoaded(false);
+        const startedAt = getBootstrapTimestamp();
         const abortController = new AbortController();
         referenceDataAbortRef.current = abortController;
         const request = (async () => {
             await Promise.allSettled([
                 (async () => {
+                    let source = 'empty-taxonomy-state';
                     const taxonomyRes = await fetch('/api/taskforce/taxonomy-state', { signal: abortController.signal });
                     if (!taxonomyRes.ok)
                         return;
                     const taxonomyData = await taxonomyRes.json().catch(() => ({}));
                     if (!hasWorkspaceTaxonomyStatePayload(taxonomyData)) {
+                        source = 'fallback-endpoints';
                         const [catRes, typeRes, priorityRes, taxRes] = await Promise.all([
                             fetch('/api/taskforce/categories', { signal: abortController.signal }),
                             fetch('/api/taskforce/types', { signal: abortController.signal }),
@@ -42,9 +73,17 @@ export function useTaskforceWorkspaceBootstrap(args) {
                         taxonomyData.priorities = priorityData.priorities;
                         taxonomyData.taxonomies = taxData.taxonomies;
                     }
+                    else {
+                        source = 'taxonomy-state';
+                    }
                     const normalized = normalizeWorkspaceTaxonomyStatePayload(taxonomyData);
-                    if (isWorkspaceRequestStale(requestState))
+                    if (isWorkspaceRequestStale(requestState)) {
+                        logBootstrapDebug('bootstrap_reference_data_stale_drop', {
+                            workspaceId: normalizedWorkspaceId,
+                            source
+                        });
                         return;
+                    }
                     if (normalized.categories.length > 0)
                         setCustomCategories(normalized.categories);
                     if (normalized.types.length > 0)
@@ -53,6 +92,14 @@ export function useTaskforceWorkspaceBootstrap(args) {
                         setPriorities(normalized.priorities);
                     setTaxonomies(normalized.taxonomies);
                     setTaxonomyDisplayLabels(normalized.displayLabels || {});
+                    logBootstrapDebug('bootstrap_reference_data_source', {
+                        workspaceId: normalizedWorkspaceId,
+                        source,
+                        categories: normalized.categories.length,
+                        types: normalized.types.length,
+                        priorities: normalized.priorities.length,
+                        taxonomies: normalized.taxonomies.length
+                    });
                 })(),
                 fetchWorkflows(),
                 fetchInitiativeTemplates(),
@@ -61,6 +108,11 @@ export function useTaskforceWorkspaceBootstrap(args) {
             if (isWorkspaceRequestStale(requestState))
                 return;
             setReferenceDataLoaded(true);
+            logBootstrapDebug('bootstrap_reference_data_loaded', {
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                workspaceId: normalizedWorkspaceId,
+                force
+            });
         })();
         referenceDataRequestRef.current = { workspaceId: requestState.workspaceId, promise: request };
         try {
@@ -72,13 +124,14 @@ export function useTaskforceWorkspaceBootstrap(args) {
             if (referenceDataAbortRef.current === abortController)
                 referenceDataAbortRef.current = null;
         }
-    }, [fetchInitiativeTemplates, fetchWorkflows, getWorkspaceRequestState, isWorkspaceRequestStale, loadAvailableEnvironments, referenceDataAbortRef, referenceDataRequestRef, setCustomCategories, setCustomTypes, setPriorities, setReferenceDataLoaded, setTaxonomies, setTaxonomyDisplayLabels, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
+    }, [authSessionResolved, fetchInitiativeTemplates, fetchWorkflows, getWorkspaceRequestState, isAuthenticated, isWorkspaceRequestStale, loadAvailableEnvironments, referenceDataAbortRef, referenceDataRequestRef, runtimeMode, 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 startedAt = getBootstrapTimestamp();
         const abortController = new AbortController();
         bootstrapConfigAbortRef.current = abortController;
         try {
@@ -114,6 +167,11 @@ export function useTaskforceWorkspaceBootstrap(args) {
             }
             setConfigLoaded(true);
             markBootstrapPhase('ready');
+            logBootstrapDebug('bootstrap_config_loaded', {
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                status: res.status,
+                workspaceId: configResolvedWorkspaceId || requestState.workspaceId
+            });
             void fetchBuildInfo();
         }
         catch (error) {
@@ -125,6 +183,11 @@ export function useTaskforceWorkspaceBootstrap(args) {
             }
             markBootstrapStalled(isBootstrapTimeoutError(error) ? 'Startup checks timed out.' : 'Unable to finish startup checks.');
             setConfigLoaded(true);
+            logBootstrapDebug('bootstrap_config_failed', {
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                workspaceId: requestState.workspaceId,
+                error: error instanceof Error ? error.message : String(error)
+            });
         }
         finally {
             if (bootstrapConfigAbortRef.current === abortController)
@@ -135,6 +198,16 @@ export function useTaskforceWorkspaceBootstrap(args) {
         await fetchBootstrapConfig(options);
         await fetchReferenceData(options);
     }, [fetchBootstrapConfig, fetchReferenceData]);
+    const scheduleDeferredArchiveBootstrap = useCallback(() => {
+        if (typeof window === 'undefined')
+            return;
+        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, fetchArchive]);
     const fetchWorkspaces = useCallback(async () => {
         if (!workspaceSwitchingEnabled) {
             setAvailableWorkspaces([]);
@@ -142,6 +215,7 @@ export function useTaskforceWorkspaceBootstrap(args) {
             return { success: true, workspaces: [] };
         }
         const requestState = getWorkspaceRequestState();
+        const startedAt = getBootstrapTimestamp();
         const abortController = new AbortController();
         workspaceListAbortRef.current = abortController;
         try {
@@ -177,6 +251,12 @@ export function useTaskforceWorkspaceBootstrap(args) {
             if (runtimeMode !== 'local' && typeof data?.currentWorkspaceId === 'string' && data.currentWorkspaceId.trim().length > 0) {
                 applyResolvedWorkspaceId(data.currentWorkspaceId.trim(), { preserveNonDefaultDefault: true });
             }
+            logBootstrapDebug('bootstrap_workspaces_loaded', {
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                workspaceId: requestState.workspaceId,
+                count: workspaces.length,
+                status: res.status
+            });
             return { success: true, workspaces };
         }
         catch (error) {
@@ -184,6 +264,11 @@ export function useTaskforceWorkspaceBootstrap(args) {
                 markBootstrapStalled('Startup checks timed out.');
             setAvailableWorkspaces([]);
             workspaceListHydratedRef.current = false;
+            logBootstrapDebug('bootstrap_workspaces_failed', {
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                workspaceId: requestState.workspaceId,
+                error: error instanceof Error ? error.message : String(error)
+            });
             return { success: false, error: isAbortError(error) ? 'Workspace list request aborted.' : 'Failed to load workspaces.' };
         }
         finally {
@@ -193,6 +278,7 @@ export function useTaskforceWorkspaceBootstrap(args) {
     }, [applyResolvedWorkspaceId, fetchWithTimeout, getWorkspaceRequestState, isAbortError, isBootstrapTimeoutError, isWorkspaceEpochStale, markBootstrapStalled, runtimeMode, setAvailableWorkspaces, workspaceListAbortRef, workspaceListHydratedRef, workspaceSwitchingEnabled]);
     const fetchAssigneeOptions = useCallback(async () => {
         const requestState = getWorkspaceRequestState();
+        const startedAt = getBootstrapTimestamp();
         const abortController = new AbortController();
         assigneeOptionsAbortRef.current = abortController;
         setAssigneeOptionsLoaded(false);
@@ -218,6 +304,19 @@ export function useTaskforceWorkspaceBootstrap(args) {
                 setAssigneeOptionsLoaded(true);
                 return { success: false, error: data?.error || `Failed to load assignee options (${assigneeResult.status})` };
             }
+            const normalizedAuthUserId = String(authUserId || '').trim();
+            const currentUserAvatarUrl = String(authUserAvatarUrl || '').trim();
+            const resolveMemberAvatarUrl = (candidate, fallbackValue) => {
+                const candidateAvatarUrl = typeof candidate?.avatarUrl === 'string' && candidate.avatarUrl.trim().length > 0
+                    ? candidate.avatarUrl.trim()
+                    : '';
+                if (candidateAvatarUrl)
+                    return candidateAvatarUrl;
+                const candidateUserId = String(candidate?.userId || fallbackValue || '').trim();
+                return normalizedAuthUserId && candidateUserId === normalizedAuthUserId && currentUserAvatarUrl
+                    ? currentUserAvatarUrl
+                    : null;
+            };
             const assignees = Array.isArray(data?.assignees) ? data.assignees : [];
             const directOptions = assignees.map((entry) => {
                 const value = String(entry?.value || '').trim();
@@ -225,21 +324,35 @@ export function useTaskforceWorkspaceBootstrap(args) {
                 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' };
+                    return {
+                        value,
+                        label: String(entry?.label || value).trim() || value,
+                        icon: String(entry?.icon || 'Bot'),
+                        color: String(entry?.color || '#8b5cf6'),
+                        kind: 'agent',
+                        avatarUrl: typeof entry?.avatarUrl === 'string' && entry.avatarUrl.trim().length > 0 ? entry.avatarUrl.trim() : null
+                    };
                 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 {
+                        value,
+                        label: String(entry?.label || value).trim() || value,
+                        icon: String(entry?.icon || 'User'),
+                        color: String(entry?.color || '#22c55e'),
+                        kind: 'member',
+                        avatarUrl: resolveMemberAvatarUrl(entry, value)
+                    };
                 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
+                displayName: typeof candidate?.displayName === 'string' ? candidate.displayName : null,
+                avatarUrl: resolveMemberAvatarUrl(candidate)
             })).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') {
@@ -251,7 +364,8 @@ export function useTaskforceWorkspaceBootstrap(args) {
                 const workspaceMemberCandidates = users.map((candidate) => ({
                     userId: String(candidate?.userId || '').trim(),
                     email: String(candidate?.email || '').trim().toLowerCase(),
-                    displayName: typeof candidate?.displayName === 'string' ? candidate.displayName : null
+                    displayName: typeof candidate?.displayName === 'string' ? candidate.displayName : null,
+                    avatarUrl: resolveMemberAvatarUrl(candidate)
                 })).filter((candidate) => candidate.userId);
                 memberCandidates = Array.from(new Map([...fallbackCandidates, ...workspaceMemberCandidates].map((candidate) => [candidate.userId, candidate])).values());
             }
@@ -263,6 +377,11 @@ export function useTaskforceWorkspaceBootstrap(args) {
                 return { success: false, error: 'Workspace changed while loading assignee options.' };
             setAssigneeOptions(merged);
             setAssigneeOptionsLoaded(true);
+            logBootstrapDebug('bootstrap_assignee_options_loaded', {
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                workspaceId: requestState.workspaceId,
+                count: merged.length
+            });
             return { success: true };
         }
         catch (error) {
@@ -270,20 +389,32 @@ export function useTaskforceWorkspaceBootstrap(args) {
                 setAssigneeOptions(createDefaultAssigneeOptions());
                 setAssigneeOptionsLoaded(true);
             }
+            logBootstrapDebug('bootstrap_assignee_options_failed', {
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                workspaceId: requestState.workspaceId,
+                error: error instanceof Error ? error.message : String(error)
+            });
             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]);
+    }, [assigneeOptionsAbortRef, authSessionResolved, authUserAvatarUrl, 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.' };
+        const previousWorkspaceId = String(currentWorkspaceIdRef.current || '').trim() || 'default';
+        const startedAt = getBootstrapTimestamp();
         try {
+            logBootstrapDebug('bootstrap_workspace_switch_started', {
+                fromWorkspaceId: previousWorkspaceId,
+                toWorkspaceId: normalizedWorkspaceId,
+                hydrate: options?.hydrate !== false
+            });
             const res = await fetch('/api/taskforce/session/workspace', {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
@@ -309,17 +440,36 @@ export function useTaskforceWorkspaceBootstrap(args) {
                     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()]);
+                await Promise.all([
+                    fetchConfig(),
+                    fetchWorkspaces(),
+                    refreshTaskCollections({ isSilent: false }),
+                    loadWorkspaceSyncState()
+                ]);
+                void fetchPlanningEntities({ ignoreAuthGuard: true });
             }
+            logBootstrapDebug('bootstrap_workspace_switch_completed', {
+                fromWorkspaceId: previousWorkspaceId,
+                toWorkspaceId: normalizedWorkspaceId,
+                hydrate: options?.hydrate !== false,
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt))
+            });
             return { success: true };
         }
-        catch {
+        catch (error) {
+            logBootstrapDebug('bootstrap_workspace_switch_failed', {
+                fromWorkspaceId: previousWorkspaceId,
+                toWorkspaceId: normalizedWorkspaceId,
+                hydrate: options?.hydrate !== false,
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                error: error instanceof Error ? error.message : String(error)
+            });
             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]);
+    }, [abortWorkspaceScopedRequests, activeTab, checkAuthSession, commitCurrentWorkspaceId, currentWorkspaceIdRef, fetchConfig, fetchPlanningEntities, 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);
@@ -366,59 +516,188 @@ export function useTaskforceWorkspaceBootstrap(args) {
     }, [commitCurrentWorkspaceId, currentWorkspaceId, currentWorkspaceIdRef, fetchWorkspaces, markBootstrapPhase, markBootstrapStalled, setWorkspaceBootstrapPending, switchWorkspace, workspaceSelectionScope, workspaceSwitchingEnabled]);
     const retryBootstrapChecks = useCallback(async () => {
         markBootstrapPhase('auth');
+        const startedAt = getBootstrapTimestamp();
+        logBootstrapDebug('bootstrap_retry_started', {
+            workspaceId: String(currentWorkspaceIdRef.current || 'default').trim() || 'default'
+        });
         const authenticated = await checkAuthSession({ force: true });
+        let workspaceSetupRequired = false;
         if (workspaceSwitchingEnabled && authenticated) {
             const workspaceResolution = await resolveWorkspaceAfterAuth();
             if (!workspaceResolution.success || workspaceResolution.workspaceSetupRequired) {
                 await fetchConfig({ ignoreAuthGuard: true });
+                logBootstrapDebug('bootstrap_retry_completed', {
+                    workspaceId: String(currentWorkspaceIdRef.current || 'default').trim() || 'default',
+                    authenticated,
+                    workspaceSetupRequired: workspaceResolution.workspaceSetupRequired === true,
+                    success: workspaceResolution.success,
+                    durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt))
+                });
                 return;
             }
         }
-        await fetchConfig({ ignoreAuthGuard: true });
-    }, [checkAuthSession, fetchConfig, markBootstrapPhase, resolveWorkspaceAfterAuth, workspaceSwitchingEnabled]);
+        setWorkspaceBootstrapPending(true);
+        try {
+            await fetchConfig({ ignoreAuthGuard: true });
+            if (authenticated && !workspaceSetupRequired) {
+                await Promise.all([
+                    fetchTasks(true, { ignoreAuthGuard: true }),
+                    fetchReferenceData({ ignoreAuthGuard: true, force: true })
+                ]);
+                void fetchPlanningEntities({ ignoreAuthGuard: true });
+            }
+            logBootstrapDebug('bootstrap_retry_completed', {
+                workspaceId: String(currentWorkspaceIdRef.current || 'default').trim() || 'default',
+                authenticated,
+                workspaceSetupRequired,
+                success: true,
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt))
+            });
+        }
+        finally {
+            setWorkspaceBootstrapPending(false);
+        }
+    }, [checkAuthSession, currentWorkspaceIdRef, fetchConfig, fetchPlanningEntities, fetchReferenceData, fetchTasks, markBootstrapPhase, resolveWorkspaceAfterAuth, setWorkspaceBootstrapPending, workspaceSwitchingEnabled]);
+    const runCloudBootstrap = useCallback(async (options) => {
+        const reason = options?.reason || 'initial-load';
+        const ignoreAuthGuard = options?.ignoreAuthGuard === true;
+        const tasksSilent = options?.tasksSilent !== false;
+        const includeDeferredArchive = options?.includeDeferredArchive !== false;
+        const startedAt = getBootstrapTimestamp();
+        markBootstrapPhase('auth');
+        const authenticated = await checkAuthSession({ force: true });
+        if (!authenticated) {
+            await fetchConfig({ ignoreAuthGuard: true });
+            logBootstrapDebug('cloud_bootstrap_completed', {
+                reason,
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                authenticated: false,
+                workspaceSetupRequired: false,
+                success: false
+            });
+            return { success: false, authenticated: false, workspaceSetupRequired: false, error: 'Sign in required.', code: 'AUTH_REQUIRED' };
+        }
+        if (workspaceSwitchingEnabled) {
+            const workspaceResolution = await resolveWorkspaceAfterAuth();
+            if (!workspaceResolution.success) {
+                await fetchConfig({ ignoreAuthGuard: true });
+                logBootstrapDebug('cloud_bootstrap_completed', {
+                    reason,
+                    durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                    authenticated: true,
+                    workspaceSetupRequired: false,
+                    success: false,
+                    error: workspaceResolution.error || 'Workspace resolution failed.'
+                });
+                return {
+                    success: false,
+                    authenticated: true,
+                    workspaceSetupRequired: false,
+                    error: workspaceResolution.error || 'Unable to resolve workspace access.',
+                    code: workspaceResolution.code
+                };
+            }
+            if (workspaceResolution.workspaceSetupRequired) {
+                await fetchConfig({ ignoreAuthGuard: true });
+                logBootstrapDebug('cloud_bootstrap_completed', {
+                    reason,
+                    durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                    authenticated: true,
+                    workspaceSetupRequired: true,
+                    success: true
+                });
+                return { success: true, authenticated: true, workspaceSetupRequired: true };
+            }
+        }
+        setWorkspaceBootstrapPending(true);
+        try {
+            await fetchBootstrapConfig({ ignoreAuthGuard });
+            await Promise.all([
+                fetchTasks(tasksSilent, { ignoreAuthGuard }),
+                fetchReferenceData({ ignoreAuthGuard })
+            ]);
+            void fetchPlanningEntities({ ignoreAuthGuard });
+            if (includeDeferredArchive) {
+                scheduleDeferredArchiveBootstrap();
+            }
+            logBootstrapDebug('cloud_bootstrap_completed', {
+                reason,
+                durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                authenticated: true,
+                workspaceSetupRequired: false,
+                success: true,
+                workspaceId: String(currentWorkspaceIdRef.current || 'default').trim() || 'default'
+            });
+            return { success: true, authenticated: true, workspaceSetupRequired: false };
+        }
+        finally {
+            setWorkspaceBootstrapPending(false);
+        }
+    }, [
+        checkAuthSession,
+        currentWorkspaceIdRef,
+        fetchBootstrapConfig,
+        fetchPlanningEntities,
+        fetchReferenceData,
+        fetchTasks,
+        markBootstrapPhase,
+        resolveWorkspaceAfterAuth,
+        scheduleDeferredArchiveBootstrap,
+        setWorkspaceBootstrapPending,
+        workspaceSwitchingEnabled
+    ]);
     useEffect(() => {
         if (!shouldDeferProtectedApiCalls && !shouldBlockProtectedApiCalls && !hasBootstrappedDataRef.current) {
             hasBootstrappedDataRef.current = true;
             void (async () => {
+                const startedAt = getBootstrapTimestamp();
                 if (runtimeMode === 'cloud' && authSessionResolved && isAuthenticated) {
-                    const workspaceResolution = await resolveWorkspaceAfterAuth();
-                    if (!workspaceResolution.success || workspaceResolution.workspaceSetupRequired) {
-                        await fetchBootstrapConfig();
-                        void fetchReferenceData();
+                    const result = await runCloudBootstrap({
+                        reason: 'initial-load',
+                        tasksSilent: false,
+                        includeDeferredArchive: true
+                    });
+                    if (!result.success || result.workspaceSetupRequired) {
                         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);
+                else {
+                    await Promise.all([
+                        fetchBootstrapConfig(),
+                        fetchTasks(false),
+                        fetchReferenceData()
+                    ]);
+                    void fetchPlanningEntities();
+                }
+                if (runtimeMode !== 'cloud') {
+                    scheduleDeferredArchiveBootstrap();
                 }
+                logBootstrapDebug('bootstrap_initial_load_completed', {
+                    durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                    runtimeMode,
+                    workspaceId: String(currentWorkspaceIdRef.current || 'default').trim() || 'default'
+                });
             })();
         }
-    }, [archiveBootstrapTimerRef, authSessionResolved, fetchArchive, fetchBootstrapConfig, fetchPlanningEntities, fetchReferenceData, fetchTasks, hasBootstrappedDataRef, isAuthenticated, resolveWorkspaceAfterAuth, runtimeMode, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
+    }, [authSessionResolved, currentWorkspaceIdRef, fetchBootstrapConfig, fetchPlanningEntities, fetchReferenceData, fetchTasks, hasBootstrappedDataRef, isAuthenticated, runCloudBootstrap, runtimeMode, scheduleDeferredArchiveBootstrap, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
     useEffect(() => {
-        if (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls || workspaceSelectionScope === 'bootstrap' || !hasBootstrappedDataRef.current)
+        if (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls || workspaceBootstrapPending || 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]);
+    }, [currentWorkspaceId, fetchConfig, hasBootstrappedDataRef, lastConfigRefreshKeyRef, runtimeMode, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls, workspaceBootstrapPending, workspaceSelectionScope]);
     useEffect(() => {
-        if (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls)
+        if (shouldDeferProtectedApiCalls || shouldBlockProtectedApiCalls || workspaceBootstrapPending)
             return;
         const loadKey = currentWorkspaceId;
         if (lastWorkspaceSyncStateLoadKeyRef.current === loadKey)
             return;
         lastWorkspaceSyncStateLoadKeyRef.current = loadKey;
         void loadWorkspaceSyncState();
-    }, [currentWorkspaceId, lastWorkspaceSyncStateLoadKeyRef, loadWorkspaceSyncState, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
+    }, [currentWorkspaceId, lastWorkspaceSyncStateLoadKeyRef, loadWorkspaceSyncState, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls, workspaceBootstrapPending]);
     useEffect(() => {
         if (runtimeMode !== 'cloud' || !authSessionResolved || !isAuthenticated) {
             if (runtimeMode !== 'cloud')
@@ -426,9 +705,11 @@ export function useTaskforceWorkspaceBootstrap(args) {
             workspaceListHydratedRef.current = false;
             return;
         }
+        if (workspaceBootstrapPending)
+            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 };
+    }, [authSessionResolved, fetchWorkspaces, hasBootstrappedDataRef, isAuthenticated, runtimeMode, setAvailableWorkspaces, workspaceBootstrapPending, workspaceListHydratedRef]);
+    return { fetchReferenceData, fetchBootstrapConfig, fetchConfig, fetchWorkspaces, fetchAssigneeOptions, switchWorkspace, resolveWorkspaceAfterAuth, retryBootstrapChecks, runCloudBootstrap };
 }

package/dist/localization/locales/en-US.d.ts

@@ -12,7 +12,6 @@ export interface MessageCatalog {
         updatedLabel: string;
         completedLabel: string;
         emptyValue: string;
-        parentCannotSchedule: string;
         dueBeforeScheduled: string;
         overdue: string;
     };

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

@@ -12,7 +12,6 @@ export const enUS = {
         updatedLabel: 'Updated:',
         completedLabel: 'Completed:',
         emptyValue: '—',
-        parentCannotSchedule: 'Parent tasks cannot be scheduled. Schedule leaf tasks instead.',
         dueBeforeScheduled: 'Due date is before scheduled date.',
         overdue: 'This task is overdue.'
     },

package/dist/localization/locales/es-419.js

@@ -12,7 +12,6 @@ export const es419 = {
         updatedLabel: 'Actualizado:',
         completedLabel: 'Completado:',
         emptyValue: '—',
-        parentCannotSchedule: 'Las tareas padre no se pueden programar. Programa tareas hoja en su lugar.',
         dueBeforeScheduled: 'La fecha de vencimiento es anterior a la fecha programada.',
         overdue: 'Esta tarea esta vencida.'
     },

package/dist/localization/locales/pt-BR.js

@@ -12,7 +12,6 @@ export const ptBR = {
         updatedLabel: 'Atualizado:',
         completedLabel: 'Concluido:',
         emptyValue: '—',
-        parentCannotSchedule: 'Tarefas pai nao podem ser agendadas. Agende as tarefas folha.',
         dueBeforeScheduled: 'A data de vencimento e anterior a data agendada.',
         overdue: 'Esta tarefa esta atrasada.'
     },

package/dist/mcp/documentAssetRegistrar.js

@@ -61,7 +61,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('get_image', (context) => ({
-        description: context.describeTool('Get a single image by asset id or image reference such as I-123. Use this first when the user references an image, then use get_annotated_attachment_sessions and read_annotated_attachment_payload for annotation details.'),
+        description: context.describeTool('Get a single image by asset id or image reference such as I-123. Use this first when the user references an image, then use get_annotated_attachment_sessions and read_annotated_attachment_payload for annotation details. When the image is being used for UI, placement, or visual correction feedback, read the saved annotation payload before making changes.'),
         inputSchema: {
             properties: {
                 id: stringProperty('Image asset id or image reference such as I-123.'),
@@ -99,7 +99,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('get_annotated_attachment_sessions', (context) => ({
-        description: context.describeTool('List saved annotation sessions for one image. Use this after get_image when you need the saved annotation sessions before opening one payload.'),
+        description: context.describeTool('List saved annotation sessions for one image. Use this after get_image when you need the saved annotation sessions before opening one payload. If the user is pointing at a visual target in I-123, do not stop at the screenshot alone; inspect the saved session payload next.'),
         inputSchema: {
             properties: {
                 imageId: stringProperty('Image asset id or image reference such as I-123.'),
@@ -108,7 +108,7 @@ export function registerDocumentAssetTools(registerTool, executeTool) {
         },
     }));
     register('read_annotated_attachment_payload', (context) => ({
-        description: context.describeTool('Read the structured payload for one annotated attachment session, including markers, geometry, and derived crop hints.'),
+        description: context.describeTool('Read the structured payload for one annotated attachment session, including markers, geometry, and derived crop hints. Use this as the authoritative instruction source when I-123 is being used for UI placement or visual change requests.'),
         inputSchema: {
             properties: {
                 sessionId: stringProperty('Annotated attachment session id.'),