@taskforcehq/taskforce 0.3.306 → 0.3.307

package/dist/hooks/useFilterSort.test.js

@@ -26,7 +26,8 @@ function makeTask(overrides) {
         comments: overrides.comments || [],
         attachments: overrides.attachments || [],
         activity: overrides.activity || [],
-        taskEvents: overrides.taskEvents || []
+        taskEvents: overrides.taskEvents || [],
+        referenceLabel: overrides.referenceLabel
     };
 }
 describe('useFilterSort', () => {
@@ -107,6 +108,91 @@ describe('useFilterSort', () => {
         expect(result.current.searchAgnosticTasks.map((task) => task.id)).toEqual(['known-task', 'unknown-task']);
         expect(result.current.filteredArchive.map((task) => task.id)).toEqual(['unknown-archived-task']);
     });
+    it('matches task reference labels when the search query has surrounding spaces or pasted formatting', async () => {
+        const matchingTask = makeTask({
+            id: 'matching-task',
+            title: 'Reference match',
+            referenceLabel: 'T-123'
+        });
+        const otherTask = makeTask({
+            id: 'other-task',
+            title: 'Other task',
+            referenceLabel: 'T-456'
+        });
+        const archivedMatch = makeTask({
+            id: 'archived-match',
+            title: 'Archived reference match',
+            referenceLabel: 'T-123',
+            isArchived: true
+        });
+        const { result } = renderHook(() => useFilterSort({
+            tasks: [matchingTask, otherTask],
+            archivedTasks: [archivedMatch],
+            activeCategories,
+            activeTypes,
+            priorities,
+            taxonomies: [],
+            configLoaded: true,
+            referenceDataLoaded: true,
+            assigneeOptionsLoaded: true,
+            assigneeOptions
+        }));
+        await waitFor(() => {
+            expect(result.current.hasInitedFilters).toBe(true);
+        });
+        act(() => {
+            result.current.setSearchQuery(' T - 123 ');
+        });
+        expect(result.current.filteredTasks.map((task) => task.id)).toEqual(['matching-task']);
+        expect(result.current.filteredArchive.map((task) => task.id)).toEqual(['archived-match']);
+        act(() => {
+            result.current.setSearchQuery('t–123');
+        });
+        expect(result.current.filteredTasks.map((task) => task.id)).toEqual(['matching-task']);
+        act(() => {
+            result.current.setSearchQuery('   ');
+        });
+        expect(result.current.filteredTasks.map((task) => task.id)).toEqual(['matching-task', 'other-task']);
+    });
+    it('matches tokenized search text and task metadata labels', async () => {
+        const matchingTask = makeTask({
+            id: 'matching-task',
+            title: 'Billing API cleanup',
+            category: 'ops',
+            priority: 3,
+            assignee: 'member-1'
+        });
+        const otherTask = makeTask({
+            id: 'other-task',
+            title: 'Marketing copy cleanup',
+            category: 'default',
+            priority: 1,
+            assignee: 'unassigned'
+        });
+        const { result } = renderHook(() => useFilterSort({
+            tasks: [matchingTask, otherTask],
+            archivedTasks: [],
+            activeCategories,
+            activeTypes,
+            priorities,
+            taxonomies: [],
+            configLoaded: true,
+            referenceDataLoaded: true,
+            assigneeOptionsLoaded: true,
+            assigneeOptions
+        }));
+        await waitFor(() => {
+            expect(result.current.hasInitedFilters).toBe(true);
+        });
+        act(() => {
+            result.current.setSearchQuery('api billing');
+        });
+        expect(result.current.filteredTasks.map((task) => task.id)).toEqual(['matching-task']);
+        act(() => {
+            result.current.setSearchQuery('Member One');
+        });
+        expect(result.current.filteredTasks.map((task) => task.id)).toEqual(['matching-task']);
+    });
     it('still excludes unknown values when the user selects a subset filter', async () => {
         const knownTask = makeTask({
             id: 'known-task',

package/dist/hooks/useSyncOrchestrator.js

@@ -26,6 +26,7 @@ import { useWorkspaceSyncController } from './useWorkspaceSyncController';
 import { normalizeTaskforceTheme } from '../utils/theme';
 import { useRealtimeSync } from './useRealtimeSync';
 import { TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT } from '../utils/contextAssetEvents';
+import { TASKFORCE_AI_PROFILES_MUTATED_EVENT } from '../utils/aiProfileEvents';
 import { setLocale as setAppLocale } from '../localization';
 import { normalizeTaskFromApi } from '../utils/taskNormalization.js';
 import { normalizeSyncEventDetails } from '../utils/syncEventDetails';
@@ -642,7 +643,7 @@ export function useSyncOrchestrator(input) {
         return buildWorkspaceSyncPayloadModel({
             tasks: workspaceTasksRef.current,
             archivedTasks: workspaceArchivedTasksRef.current,
-            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current),
+            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current, workspaceInitiativesRef.current, workspaceWorkstreamsRef.current),
             lastPushedTaskIds: workspaceLastPushedTaskIdsRef.current,
             pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
             pendingDeletedTaskWatermarks: workspaceDeletedTaskWatermarksRef.current,
@@ -720,7 +721,7 @@ export function useSyncOrchestrator(input) {
             workspaceId: currentWorkspaceId,
             tasks: workspaceTasksRef.current,
             archivedTasks: workspaceArchivedTasksRef.current,
-            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current),
+            taskEvents: flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current, workspaceInitiativesRef.current, workspaceWorkstreamsRef.current),
             pendingDeletedTaskIds: workspaceDeletedTaskIdsRef.current,
             initiatives: workspaceInitiativesRef.current,
             workstreams: workspaceWorkstreamsRef.current,
@@ -767,10 +768,11 @@ export function useSyncOrchestrator(input) {
             isArchived: Boolean(workstream.isArchived)
         }))
             .sort((left, right) => left.id.localeCompare(right.id)),
-        taskEvents: flattenTaskEvents(tasks || [], archivedTasks || [])
+        taskEvents: flattenTaskEvents(tasks || [], archivedTasks || [], initiatives || [], workstreams || [])
             .map((event) => ({
             id: String(event.id || '').trim(),
-            taskId: String(event.taskId || '').trim(),
+            entityType: String(event.entityType || 'task').trim(),
+            entityId: String(event.entityId || event.taskId || '').trim(),
             createdAt: String(event.createdAt || '').trim(),
             action: String(event.action || '').trim(),
         }))
@@ -1005,6 +1007,37 @@ export function useSyncOrchestrator(input) {
             markWorkspaceSyncReferenceSnapshotReady('assets');
         }
     }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated, markWorkspaceSyncReferenceSnapshotReady]);
+    const refreshWorkspaceSyncPlanningEntitiesSnapshot = useCallback(async () => {
+        if (runtimeMode !== 'local')
+            return;
+        if (!isValidWorkspaceKey(currentWorkspaceId))
+            return;
+        if (cloudAuthConfigured && (!authSessionResolved || !isAuthenticated))
+            return;
+        try {
+            const res = await fetch(`/api/taskforce/planning/bootstrap?workspaceId=${encodeURIComponent(currentWorkspaceId)}`, {
+                method: 'GET',
+                credentials: 'include'
+            });
+            if (!res.ok)
+                return;
+            const data = await res.json().catch(() => ({}));
+            const nextInitiatives = Array.isArray(data?.initiatives)
+                ? data.initiatives.filter((entry) => (Boolean(entry && typeof entry === 'object' && typeof entry.id === 'string')))
+                : [];
+            const nextWorkstreams = Array.isArray(data?.workstreams)
+                ? data.workstreams.filter((entry) => (Boolean(entry && typeof entry === 'object' && typeof entry.id === 'string')))
+                : [];
+            workspaceInitiativesRef.current = nextInitiatives;
+            workspaceWorkstreamsRef.current = nextWorkstreams;
+        }
+        catch (error) {
+            logSyncDebug('planning_snapshot_refresh_failed', {
+                workspaceId: currentWorkspaceId,
+                error: String(error?.message || error || '')
+            });
+        }
+    }, [runtimeMode, currentWorkspaceId, cloudAuthConfigured, authSessionResolved, isAuthenticated]);
     const refreshWorkspaceSyncDocumentReviewSessionsSnapshot = useCallback(async () => {
         if (runtimeMode !== 'local')
             return;
@@ -1196,7 +1229,7 @@ export function useSyncOrchestrator(input) {
         workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map(workspaceSyncAnnotatedAttachmentSessionsRef.current
             .map((entry) => [String(entry?.id || '').trim(), String(entry?.updatedAt || entry?.createdAt || '').trim()])
             .filter(([id]) => id.length > 0));
-        workspaceLastPushedTaskEventWatermarksRef.current = new Map(flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current)
+        workspaceLastPushedTaskEventWatermarksRef.current = new Map(flattenTaskEvents(workspaceTasksRef.current, workspaceArchivedTasksRef.current, workspaceInitiativesRef.current, workspaceWorkstreamsRef.current)
             .map((entry) => [String(entry?.id || '').trim(), String(entry?.createdAt || '').trim()])
             .filter(([id]) => id.length > 0));
         const persisted = persistWorkspaceSyncWatermarksSnapshotBestEffort();
@@ -1292,6 +1325,7 @@ export function useSyncOrchestrator(input) {
         refreshWorkspaceSyncMarkdownDocumentsSnapshot,
         refreshWorkspaceSyncAiProfilesSnapshot,
         refreshWorkspaceSyncAssetsSnapshot,
+        refreshWorkspaceSyncPlanningEntitiesSnapshot,
         refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
         refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot,
         refreshLocalWorkspaceTaskCollections,
@@ -1373,6 +1407,7 @@ export function useSyncOrchestrator(input) {
         refreshWorkspaceSyncMarkdownDocumentsSnapshot,
         refreshWorkspaceSyncAiProfilesSnapshot,
         refreshWorkspaceSyncAssetsSnapshot,
+        refreshWorkspaceSyncPlanningEntitiesSnapshot,
         refreshWorkspaceSyncDocumentReviewSessionsSnapshot,
         refreshWorkspaceSyncAnnotatedAttachmentSessionsSnapshot,
         refreshLocalWorkspaceTaskCollections,
@@ -1656,7 +1691,16 @@ export function useSyncOrchestrator(input) {
                 return;
             refreshWorkspaceSyncContextAssetSnapshots();
         };
+        const handleAiProfilesMutated = (event) => {
+            const detail = event.detail;
+            const eventWorkspaceId = String(detail?.workspaceId || '').trim() || 'default';
+            if (eventWorkspaceId !== currentWorkspaceId)
+                return;
+            void refreshWorkspaceSyncAiProfilesSnapshot();
+            void refreshWorkspaceSyncAssetsSnapshot();
+        };
         window.addEventListener(TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT, handleContextAssetsMutated);
+        window.addEventListener(TASKFORCE_AI_PROFILES_MUTATED_EVENT, handleAiProfilesMutated);
         const docsIntervalId = window.setInterval(() => {
             void refreshWorkspaceSyncMarkdownDocumentsSnapshot();
         }, workspaceDocumentsRefreshIntervalMs);
@@ -1674,6 +1718,7 @@ export function useSyncOrchestrator(input) {
         }, workspaceDocumentsRefreshIntervalMs);
         return () => {
             window.removeEventListener(TASKFORCE_CONTEXT_ASSETS_MUTATED_EVENT, handleContextAssetsMutated);
+            window.removeEventListener(TASKFORCE_AI_PROFILES_MUTATED_EVENT, handleAiProfilesMutated);
             window.clearInterval(docsIntervalId);
             window.clearInterval(aiProfilesIntervalId);
             window.clearInterval(assetsIntervalId);

package/dist/hooks/useTaskforce.d.ts

@@ -1,3 +1,38 @@
+/**
+ * useTaskforce
+ *
+ * Central React hook for the Taskforce task-management system.
+ * Orchestrates all application state: runtime config, auth, workspace,
+ * bootstrap, task data, filtering/sorting, form editing, settings,
+ * sync, and UI notices.
+ *
+ * SECTION MAP (use Ctrl+F on the === markers to jump):
+ *   === SECTION: Runtime Config ===         Line ~189  — URL resolution, cloud/local mode detection
+ *   === SECTION: Settings State ===         Line ~388  — Theme, shortcut, locale, feature flags
+ *   === SECTION: Workspace Storage ===      Line ~415  — workspaceStorageScope, project root/name
+ *   === SECTION: Auth State ===             Line ~426  — isAuthenticated, authBlocked, userId, beta access
+ *   === SECTION: Bootstrap State ===        Line ~442  — bootstrapPhase, setupState, runtimeCapabilities
+ *   === SECTION: Fetch Intercept ===        Line ~490  — window.fetch patch for cloud API routing
+ *   === SECTION: Workflow Templates ===     Line ~577  — fetchWorkflows, fetchInitiativeTemplates
+ *   === SECTION: Export State ===           Line ~678  — exportEnvironment, exportWorkflowsPath
+ *   === SECTION: Task State ===             Line ~1065 — tasks, archivedTasks, editingTaskId
+ *   === SECTION: Filter & Sort State ===    Line ~1394 — searchQuery, filterCategories, sortBy, sortOrder
+ *   === SECTION: UI State ===               Line ~1469 — uiStateReady, persisted UI preferences
+ *   === SECTION: Config Fetch ===           Line ~1578 — fetchConfig (the main bootstrap loader)
+ *   === SECTION: Workspace Actions ===      Line ~1855 — fetchWorkspaces, switchWorkspace, createWorkspace
+ *   === SECTION: Auth Actions ===           Line ~2210 — loginWithCredentials, logout, invite flows
+ *   === SECTION: Task Fetch ===             Line ~2158 — fetchTasks, fetchArchive, refreshTaskCollections
+ *   === SECTION: Bootstrap Effects ===      Line ~2641 — initialization useEffects
+ *   === SECTION: Filtering Logic ===        Line ~3068 — filteredTasks, searchAgnosticTasks, filteredArchive
+ *   === SECTION: Navigation ===             Line ~3410 — setActiveTab, handleNavigation
+ *   === SECTION: Form ===                   Line ~3489 — resetForm, handleEdit, handleSubmit, saveTask
+ *   === SECTION: Task CRUD ===              Line ~3691 — handleDelete, handleUpdateTask, handleToggle*
+ *   === SECTION: Planning Links ===         Line ~4129 — workstream and initiative link handlers
+ *   === SECTION: Category/Type Mgmt ===     Line ~4462 — handleSaveCategory, handleRemoveCategory
+ *   === SECTION: Settings Model ===         Line ~4625 — settingsModel object
+ *   === SECTION: Return Value ===           Line ~4817 — final return object (public API shape)
+ */
+import { type Dispatch, type SetStateAction } from 'react';
 import type { TaskforceConfig, TaskforceTheme, Comment, AttachmentItem, CategoryConfig, TaskItem, TaxonomyDefinition, Environment, TaskAssignee, TaskStatus, DeletedTaskRecord, InitiativeItem, WorkstreamItem, ChecklistItem, PlanningBootstrapWorkstreamTaskSummary } from '../types';
 import { type FirstClassTaxonomyDisplayLabels } from '../shared/taxonomyState.js';
 import type { UiNotice } from '../utils/uiNotice';
@@ -106,31 +141,31 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
         showTaskCardStatusLabel: boolean;
     };
     isOpen: boolean;
-    setIsOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setIsOpen: Dispatch<SetStateAction<boolean>>;
     activeTab: "tasks" | "settings" | "add";
     setActiveTab: (tab: "add" | "tasks" | "settings") => void;
     currentTheme: "light" | "dawn" | "dark" | "midnight";
-    setCurrentTheme: import("react").Dispatch<import("react").SetStateAction<"light" | "dawn" | "dark" | "midnight">>;
+    setCurrentTheme: Dispatch<SetStateAction<"light" | "dawn" | "dark" | "midnight">>;
     configLoaded: boolean;
     storagePath: string;
     saveSettings: () => Promise<boolean>;
     pathSaved: boolean;
     keyShortcut: string;
-    setKeyShortcut: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setKeyShortcut: Dispatch<SetStateAction<string>>;
     globalWeekStartsOn: WeekStartsOn;
     locale: "en-US" | "es-419" | "pt-BR";
     supportedLocales: ("en-US" | "es-419" | "pt-BR")[];
     saveLocale: (nextLocale: string) => Promise<boolean>;
     jsonBackupEnabled: boolean;
-    setJsonBackupEnabled: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setJsonBackupEnabled: Dispatch<SetStateAction<boolean>>;
     manualComplexityEnabled: boolean;
     checklistDropdownEnabled: boolean;
     showTaskCardStatusLabel: boolean;
-    setManualComplexityEnabled: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setManualComplexityEnabled: Dispatch<SetStateAction<boolean>>;
     mcpHostRoot: string;
-    setMcpHostRoot: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setMcpHostRoot: Dispatch<SetStateAction<string>>;
     settingsSection: "mcp" | "categories" | "types" | "general" | "agents" | "taxonomy" | "documents" | "appearance-application" | "appearance-task-cards" | "appearance-task-forms" | "commands" | "workflow-editor" | "integrations" | "resources" | null;
-    setSettingsSection: import("react").Dispatch<import("react").SetStateAction<"mcp" | "categories" | "types" | "general" | "agents" | "taxonomy" | "documents" | "appearance-application" | "appearance-task-cards" | "appearance-task-forms" | "commands" | "workflow-editor" | "integrations" | "resources" | null>>;
+    setSettingsSection: Dispatch<SetStateAction<"mcp" | "categories" | "types" | "general" | "agents" | "taxonomy" | "documents" | "appearance-application" | "appearance-task-cards" | "appearance-task-forms" | "commands" | "workflow-editor" | "integrations" | "resources" | null>>;
     runtimeMode: "local" | "cloud";
     workspaceMode: "single-local" | "multi-cloud";
     workspaceSwitchingEnabled: boolean;
@@ -383,7 +418,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     }>;
     logout: () => Promise<void>;
     showFolderBrowser: boolean;
-    setShowFolderBrowser: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowFolderBrowser: Dispatch<SetStateAction<boolean>>;
     folders: string[];
     files: string[];
     currentBrowsePath: string;
@@ -392,16 +427,16 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
         type: "category";
         value: string;
     } | null;
-    setBrowserTarget: import("react").Dispatch<import("react").SetStateAction<"storage" | {
+    setBrowserTarget: Dispatch<SetStateAction<"storage" | {
         type: "category";
         value: string;
     } | null>>;
     groupBy: "category" | "type" | "priority" | "status" | "complexity" | "approach" | "assignee" | "schedule";
-    setGroupBy: import("react").Dispatch<import("react").SetStateAction<"category" | "type" | "priority" | "status" | "complexity" | "approach" | "assignee" | "schedule">>;
+    setGroupBy: Dispatch<SetStateAction<"category" | "type" | "priority" | "status" | "complexity" | "approach" | "assignee" | "schedule">>;
     activeWorkspaceModule: WorkspaceModuleId;
-    setActiveWorkspaceModule: import("react").Dispatch<import("react").SetStateAction<WorkspaceModuleId>>;
+    setActiveWorkspaceModule: Dispatch<SetStateAction<WorkspaceModuleId>>;
     emptyColumnMode: "show" | "collapse" | "hide";
-    setEmptyColumnMode: import("react").Dispatch<import("react").SetStateAction<"show" | "collapse" | "hide">>;
+    setEmptyColumnMode: Dispatch<SetStateAction<"show" | "collapse" | "hide">>;
     zenMode: boolean;
     setZenMode: () => Promise<void>;
     handleSelectPath: (path: string) => void;
@@ -438,36 +473,36 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     }[];
     taxonomies: TaxonomyDefinition[];
     searchQuery: string;
-    setSearchQuery: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setSearchQuery: Dispatch<SetStateAction<string>>;
     filterCategories: string[];
-    setFilterCategories: import("react").Dispatch<import("react").SetStateAction<string[]>>;
+    setFilterCategories: Dispatch<SetStateAction<string[]>>;
     filterTypes: string[];
-    setFilterTypes: import("react").Dispatch<import("react").SetStateAction<string[]>>;
+    setFilterTypes: Dispatch<SetStateAction<string[]>>;
     filterPriorities: (string | number)[];
-    setFilterPriorities: import("react").Dispatch<import("react").SetStateAction<(string | number)[]>>;
+    setFilterPriorities: Dispatch<SetStateAction<(string | number)[]>>;
     filterStatus: (string | number)[];
-    setFilterStatus: import("react").Dispatch<import("react").SetStateAction<(string | number)[]>>;
+    setFilterStatus: Dispatch<SetStateAction<(string | number)[]>>;
     filterAssignees: string[];
     setFilterAssignees: (nextValues: TaskAssignee[] | ((prev: TaskAssignee[]) => TaskAssignee[])) => void;
     filterTaxonomies: Record<string, (string | number)[]>;
-    setFilterTaxonomies: import("react").Dispatch<import("react").SetStateAction<Record<string, (string | number)[]>>>;
+    setFilterTaxonomies: Dispatch<SetStateAction<Record<string, (string | number)[]>>>;
     hasInitedFilters: boolean;
     sortBy: import("../utils/taxonomySorting").TaskSortKey;
-    setSortBy: import("react").Dispatch<import("react").SetStateAction<import("../utils/taxonomySorting").TaskSortKey>>;
+    setSortBy: Dispatch<SetStateAction<import("../utils/taxonomySorting").TaskSortKey>>;
     sortOrder: "asc" | "desc";
-    setSortOrder: import("react").Dispatch<import("react").SetStateAction<"asc" | "desc">>;
+    setSortOrder: Dispatch<SetStateAction<"asc" | "desc">>;
     toggleSortOrder: () => void;
     showArchive: boolean;
-    setShowArchive: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowArchive: Dispatch<SetStateAction<boolean>>;
     taskScope: TaskScope;
-    setTaskScope: import("react").Dispatch<import("react").SetStateAction<TaskScope>>;
+    setTaskScope: Dispatch<SetStateAction<TaskScope>>;
     clearFilters: () => void;
     filteredTasks: TaskItem[];
     searchAgnosticTasks: TaskItem[];
     filteredArchive: TaskItem[];
     groupedTasks: Record<string, TaskItem[]>;
     collapsedCategories: Record<string, boolean>;
-    setCollapsedCategories: import("react").Dispatch<import("react").SetStateAction<Record<string, boolean>>>;
+    setCollapsedCategories: Dispatch<SetStateAction<Record<string, boolean>>>;
     fetchTasks: (isSilent?: boolean, options?: {
         ignoreAuthGuard?: boolean;
     }) => Promise<void>;
@@ -514,50 +549,50 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     loading: boolean;
     error: string;
     title: string;
-    setTitle: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setTitle: Dispatch<SetStateAction<string>>;
     description: string;
-    setDescription: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setDescription: Dispatch<SetStateAction<string>>;
     checklistItems: ChecklistItem[];
-    setChecklistItems: import("react").Dispatch<import("react").SetStateAction<ChecklistItem[]>>;
+    setChecklistItems: Dispatch<SetStateAction<ChecklistItem[]>>;
     category: string;
-    setCategory: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setCategory: Dispatch<SetStateAction<string>>;
     type: string;
-    setType: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setType: Dispatch<SetStateAction<string>>;
     priority: string | number;
-    setPriority: import("react").Dispatch<import("react").SetStateAction<string | number>>;
+    setPriority: Dispatch<SetStateAction<string | number>>;
     complexity: string | number;
-    setComplexity: import("react").Dispatch<import("react").SetStateAction<string | number>>;
+    setComplexity: Dispatch<SetStateAction<string | number>>;
     status: TaskStatus;
-    setStatus: import("react").Dispatch<import("react").SetStateAction<TaskStatus>>;
+    setStatus: Dispatch<SetStateAction<TaskStatus>>;
     approach: string;
-    setApproach: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setApproach: Dispatch<SetStateAction<string>>;
     assignee: string;
-    setAssignee: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setAssignee: Dispatch<SetStateAction<string>>;
     scheduledDate: string;
-    setScheduledDate: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setScheduledDate: Dispatch<SetStateAction<string>>;
     dueDate: string;
-    setDueDate: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setDueDate: Dispatch<SetStateAction<string>>;
     workstreamInput: string;
-    setWorkstreamInput: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setWorkstreamInput: Dispatch<SetStateAction<string>>;
     formTaxonomies: Record<string, string | number | string[] | number[]>;
-    setFormTaxonomies: import("react").Dispatch<import("react").SetStateAction<Record<string, string | number | string[] | number[]>>>;
+    setFormTaxonomies: Dispatch<SetStateAction<Record<string, string | number | string[] | number[]>>>;
     comments: Comment[];
     newCommentText: string;
-    setNewCommentText: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setNewCommentText: Dispatch<SetStateAction<string>>;
     attachments: (string | AttachmentItem)[];
-    setAttachments: import("react").Dispatch<import("react").SetStateAction<(string | AttachmentItem)[]>>;
+    setAttachments: Dispatch<SetStateAction<(string | AttachmentItem)[]>>;
     attachmentsDirty: boolean;
-    setAttachmentsDirty: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setAttachmentsDirty: Dispatch<SetStateAction<boolean>>;
     descriptionFocused: boolean;
-    setDescriptionFocused: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setDescriptionFocused: Dispatch<SetStateAction<boolean>>;
     showMarkdownHelp: boolean;
-    setShowMarkdownHelp: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowMarkdownHelp: Dispatch<SetStateAction<boolean>>;
     showChecklist: boolean;
-    setShowChecklist: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowChecklist: Dispatch<SetStateAction<boolean>>;
     showComments: boolean;
-    setShowComments: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setShowComments: Dispatch<SetStateAction<boolean>>;
     isCapturingScreenshot: boolean;
-    setIsCapturingScreenshot: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setIsCapturingScreenshot: Dispatch<SetStateAction<boolean>>;
     handleSubmit: (event: React.FormEvent) => Promise<void>;
     resetForm: () => void;
     handleAddComment: (text: string) => Promise<void>;
@@ -566,7 +601,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     returnToPreviousTask: () => boolean;
     autoSaveState: import("./tasks/useTaskFormActions").TaskAutoSaveState;
     unsavedModalOpen: boolean;
-    setUnsavedModalOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setUnsavedModalOpen: Dispatch<SetStateAction<boolean>>;
     pendingNavigation: (() => void) | null;
     handleNavigation: (action: () => void) => void;
     handleClose: () => void;
@@ -588,11 +623,11 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     confirmScheduleWarning: () => Promise<void>;
     cancelScheduleWarning: () => void;
     tasksScrollRef: import("react").RefObject<HTMLDivElement | null>;
-    setTasksScrollPos: import("react").Dispatch<import("react").SetStateAction<number>>;
+    setTasksScrollPos: Dispatch<SetStateAction<number>>;
     exportEnvironment: string;
-    setExportEnvironment: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setExportEnvironment: Dispatch<SetStateAction<string>>;
     exportWorkflowsPath: string;
-    setExportWorkflowsPath: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setExportWorkflowsPath: Dispatch<SetStateAction<string>>;
     exportResult: {
         type: "success" | "error";
         message: string;
@@ -627,7 +662,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     validatePaths: (paths: string[]) => Promise<void>;
     getCategoryPaths: (cat: CategoryConfig) => string[];
     customCategories: CategoryConfig[];
-    setCustomCategories: import("react").Dispatch<import("react").SetStateAction<CategoryConfig[]>>;
+    setCustomCategories: Dispatch<SetStateAction<CategoryConfig[]>>;
     projectRoot: string;
     projectName: string;
     mcpScriptPath: string;

package/dist/hooks/useTaskforce.js

@@ -68,6 +68,7 @@ import { useTaskforceAuthBootstrap } from './auth/useTaskforceAuthBootstrap';
 import { deriveAuthGuardPolicy } from './auth/useAuthGuardPolicy';
 import { useTaskforceWorkspaceBootstrap } from './workspace/useTaskforceWorkspaceBootstrap';
 import { useDataVersionRefresh } from './sync/useDataVersionRefresh';
+import { BOOTSTRAP_REQUEST_TIMEOUT_MS } from './bootstrapTimeouts';
 function upsertEntityById(items, nextItem) {
     const existingIndex = items.findIndex((item) => item.id === nextItem.id);
     if (existingIndex === -1) {
@@ -89,7 +90,6 @@ const DEFAULT_CLOUD_APP_ORIGIN = (() => {
     // Safety default for local runtime cloud auth/sync fallback.
     return 'https://app.taskforcehq.ai';
 })();
-const BOOTSTRAP_REQUEST_TIMEOUT_MS = 12_000;
 const PLANNING_BOOTSTRAP_REQUEST_TIMEOUT_MS = 20_000;
 const EXPECTED_WORKSPACE_ABORT_REASONS = new Set([
     'external-abort',
@@ -944,7 +944,10 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 setPlanningBootstrapTaskSummaries([]);
                 return;
             }
-            if (bootstrapRes?.ok) {
+            if (bootstrapRes === null) {
+                throw createBootstrapTimeoutError(PLANNING_BOOTSTRAP_REQUEST_TIMEOUT_MS);
+            }
+            if (bootstrapRes.ok) {
                 bootstrapPayload = sanitizePlanningBootstrapPayload(await bootstrapRes.json().catch(() => ({})));
             }
             else {
@@ -982,7 +985,18 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         catch (err) {
             if (isExpectedWorkspaceAbortFailure(err, abortController.signal) || isAbortError(err))
                 return;
-            console.error('[Taskforce] Failed to fetch planning entities:', err);
+            const startupTimeout = isBootstrapTimeoutError(err);
+            if (startupTimeout) {
+                logBootstrapDebug('planning_bootstrap_timeout', {
+                    workspaceId: requestState.workspaceId,
+                    epoch: requestState.epoch,
+                    timeoutMs: PLANNING_BOOTSTRAP_REQUEST_TIMEOUT_MS,
+                });
+                console.warn('[Taskforce] Planning bootstrap timed out during startup; retrying in background.');
+            }
+            else {
+                console.error('[Taskforce] Failed to fetch planning entities:', err);
+            }
             if (typeof window !== 'undefined'
                 && !isWorkspaceRequestStale(requestState)
                 && initiatives.length === 0
@@ -1160,7 +1174,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         }
     });
     checkAuthSessionImplRef.current = checkAuthSessionImpl;
-    const [activeWorkspaceModule, setActiveWorkspaceModule] = useState('tasks');
+    const [activeWorkspaceModule, setActiveWorkspaceModuleState] = useState('tasks');
     const [showComments, setShowComments] = useState(false);
     const [descriptionFocused, setDescriptionFocused] = useState(false);
     const [isCapturingScreenshot, setIsCapturingScreenshot] = useState(false);
@@ -1181,10 +1195,17 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     const lastTaskSurfaceLoadKeyRef = useRef('');
     const lastSettingsSurfaceLoadKeyRef = useRef('');
     const skipNextUiStatePersistRef = useRef(false);
+    const activeWorkspaceModuleOverridePendingRef = useRef(false);
     const referenceDataRequestRef = useRef(null);
     const workspaceListHydratedRef = useRef(false);
     const hasBootstrappedDataRef = useRef(false);
     const [uiStateReady, setUiStateReady] = useState(false);
+    const setActiveWorkspaceModule = useCallback((nextModule) => {
+        if (!uiStateReady) {
+            activeWorkspaceModuleOverridePendingRef.current = true;
+        }
+        setActiveWorkspaceModuleState(nextModule);
+    }, [uiStateReady]);
     const { handleSaveSettings, handleSaveTheme, handleSaveGlobalTheme, handleJsonBackupEnabledChange, handleSaveGlobalJsonBackupEnabled, handleSaveGlobalWeekStartsOn, handleSaveLocale, handleManualComplexityEnabledChange, handleChecklistDropdownEnabledChange, handleShowTaskCardStatusLabelChange, handleResetProjectToGlobal } = useSettingsPersistence({
         keyShortcut,
         themeUseGlobalDefault,
@@ -1217,7 +1238,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         authRequiredForApiRef.current = authRequiredForApi;
         isAuthenticatedRef.current = isAuthenticated;
     }, [authSessionResolved, authRequiredForApi, isAuthenticated]);
-    const applyPersistedUiState = useCallback((state) => {
+    const applyPersistedUiState = useCallback((state, options) => {
         if (!state)
             return;
         const hasPersistedFilterState = Array.isArray(state.filterCategories)
@@ -1227,11 +1248,13 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             || Array.isArray(state.filterAssignees)
             || typeof state.filterAssigneesAllSelected === 'boolean'
             || (state.filterTaxonomies && typeof state.filterTaxonomies === 'object');
-        if (typeof state.activeWorkspaceModule === 'string') {
-            setActiveWorkspaceModule(state.activeWorkspaceModule);
-        }
-        else if (state.groupBy === 'docs') {
-            setActiveWorkspaceModule('docs');
+        if (!options?.skipActiveWorkspaceModule) {
+            if (typeof state.activeWorkspaceModule === 'string') {
+                setActiveWorkspaceModuleState(state.activeWorkspaceModule);
+            }
+            else if (state.groupBy === 'docs') {
+                setActiveWorkspaceModuleState('docs');
+            }
         }
         if (state.groupBy && state.groupBy !== 'docs')
             setGroupBy(state.groupBy);
@@ -1295,19 +1318,24 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             if (currentWorkspaceIdRef.current !== targetWorkspaceId) {
                 return;
             }
-            applyPersistedUiState(state);
+            applyPersistedUiState(state, {
+                skipActiveWorkspaceModule: activeWorkspaceModuleOverridePendingRef.current
+            });
             lastLoadedUiStateKeyRef.current = uiStateLoadKey;
         }
         catch {
             const localState = readPersistedAppUiState(workspaceUiStateScope);
             if (currentWorkspaceIdRef.current === targetWorkspaceId) {
-                applyPersistedUiState(localState);
+                applyPersistedUiState(localState, {
+                    skipActiveWorkspaceModule: activeWorkspaceModuleOverridePendingRef.current
+                });
                 lastLoadedUiStateKeyRef.current = uiStateLoadKey;
             }
         }
         finally {
             if (currentWorkspaceIdRef.current !== targetWorkspaceId)
                 return;
+            activeWorkspaceModuleOverridePendingRef.current = false;
             skipNextUiStatePersistRef.current = true;
             setUiStateReady(true);
         }
@@ -1533,10 +1561,12 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         }
         catch (versionError) {
             if (isBootstrapTimeoutError(versionError)) {
-                markBootstrapStalled('Startup checks timed out.');
+                logBootstrapDebug('build_info_timeout', {
+                    durationMs: Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - startedAt)
+                });
             }
         }
-    }, [fetchWithTimeout, isBootstrapTimeoutError, markBootstrapStalled]);
+    }, [fetchWithTimeout, isBootstrapTimeoutError]);
     const { fetchReferenceData, fetchBootstrapConfig, fetchConfig, fetchWorkspaces, fetchAssigneeOptions, switchWorkspace, resolveWorkspaceAfterAuth, retryBootstrapChecks, runCloudBootstrap } = useTaskforceWorkspaceBootstrap({
         shouldDeferProtectedApiCalls,
         shouldBlockProtectedApiCalls,