@taskforcehq/taskforce 0.3.300 → 0.3.302

package/dist/core/taskReferencePolicy.js

@@ -0,0 +1,189 @@
+import { formatLocalTaskReference, parseLocalTaskReference, parseTaskReference, } from '../utils/taskReferences.js';
+export function getTaskReferenceSequenceValue(deps, workspaceId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const row = deps.db.prepare(`
+        SELECT next_reference_number
+        FROM workspace_task_reference_sequences
+        WHERE tenant_id = ? AND workspace_id = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId);
+    return deps.sanitizeTaskReferenceNumber(row?.next_reference_number) || 0;
+}
+export function getLocalTaskReferenceSequenceValue(deps, workspaceId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const row = deps.db.prepare(`
+        SELECT next_reference_number
+        FROM workspace_local_task_reference_sequences
+        WHERE tenant_id = ? AND workspace_id = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId);
+    return deps.sanitizeTaskReferenceNumber(row?.next_reference_number) || 0;
+}
+export function getMaxTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedExcludeTaskId = String(excludeTaskId || '').trim();
+    const row = normalizedExcludeTaskId
+        ? deps.db.prepare(`
+            SELECT MAX(reference_number) AS max_reference_number
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ? AND id != ?
+        `).get(deps.tenantId, normalizedWorkspaceId, normalizedExcludeTaskId)
+        : deps.db.prepare(`
+            SELECT MAX(reference_number) AS max_reference_number
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ?
+        `).get(deps.tenantId, normalizedWorkspaceId);
+    return deps.sanitizeTaskReferenceNumber(row?.max_reference_number) || 0;
+}
+export function getMaxLocalTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedExcludeTaskId = String(excludeTaskId || '').trim();
+    const row = normalizedExcludeTaskId
+        ? deps.db.prepare(`
+            SELECT MAX(local_reference_number) AS max_reference_number
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ? AND id != ?
+        `).get(deps.tenantId, normalizedWorkspaceId, normalizedExcludeTaskId)
+        : deps.db.prepare(`
+            SELECT MAX(local_reference_number) AS max_reference_number
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ?
+        `).get(deps.tenantId, normalizedWorkspaceId);
+    return deps.sanitizeTaskReferenceNumber(row?.max_reference_number) || 0;
+}
+export function persistTaskReferenceSequence(deps, workspaceId, referenceNumber) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return;
+    deps.db.prepare(`
+        INSERT INTO workspace_task_reference_sequences (tenant_id, workspace_id, next_reference_number)
+        VALUES (?, ?, ?)
+        ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
+            next_reference_number = CASE
+                WHEN workspace_task_reference_sequences.next_reference_number < EXCLUDED.next_reference_number
+                    THEN EXCLUDED.next_reference_number
+                ELSE workspace_task_reference_sequences.next_reference_number
+            END
+    `).run(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber);
+}
+export function persistLocalTaskReferenceSequence(deps, workspaceId, referenceNumber) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return;
+    deps.db.prepare(`
+        INSERT INTO workspace_local_task_reference_sequences (tenant_id, workspace_id, next_reference_number)
+        VALUES (?, ?, ?)
+        ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
+            next_reference_number = CASE
+                WHEN workspace_local_task_reference_sequences.next_reference_number < EXCLUDED.next_reference_number
+                    THEN EXCLUDED.next_reference_number
+                ELSE workspace_local_task_reference_sequences.next_reference_number
+            END
+    `).run(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber);
+}
+export function allocateNextTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const nextReferenceNumber = Math.max(getTaskReferenceSequenceValue(deps, normalizedWorkspaceId), getMaxTaskReferenceNumber(deps, normalizedWorkspaceId, excludeTaskId)) + 1;
+    persistTaskReferenceSequence(deps, normalizedWorkspaceId, nextReferenceNumber);
+    return nextReferenceNumber;
+}
+export function allocateNextLocalTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const nextReferenceNumber = Math.max(getLocalTaskReferenceSequenceValue(deps, normalizedWorkspaceId), getMaxLocalTaskReferenceNumber(deps, normalizedWorkspaceId, excludeTaskId)) + 1;
+    persistLocalTaskReferenceSequence(deps, normalizedWorkspaceId, nextReferenceNumber);
+    return nextReferenceNumber;
+}
+export function relocateTaskReferenceConflict(deps, workspaceId, referenceNumber, claimantTaskId, updatedAt) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return null;
+    const normalizedClaimantTaskId = String(claimantTaskId || '').trim();
+    const incumbent = deps.db.prepare(`
+        SELECT id
+        FROM tasks
+        WHERE tenant_id = ? AND workspace_id = ? AND reference_number = ? AND id != ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber, normalizedClaimantTaskId);
+    const incumbentTaskId = String(incumbent?.id || '').trim();
+    if (!incumbentTaskId)
+        return null;
+    const nextReferenceNumber = allocateNextTaskReferenceNumber(deps, normalizedWorkspaceId, incumbentTaskId);
+    deps.db.prepare(`
+        UPDATE tasks
+        SET reference_number = ?, updated_at = ?
+        WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+    `).run(nextReferenceNumber, String(updatedAt || new Date().toISOString()), deps.tenantId, normalizedWorkspaceId, incumbentTaskId);
+    return { taskId: incumbentTaskId, referenceNumber: nextReferenceNumber };
+}
+export function reserveTaskReferenceNumber(deps, workspaceId, preferredReferenceNumber, currentTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const preferred = deps.sanitizeTaskReferenceNumber(preferredReferenceNumber);
+    const normalizedCurrentTaskId = String(currentTaskId || '').trim();
+    if (preferred) {
+        const existing = deps.db.prepare(`
+            SELECT id
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ? AND reference_number = ?
+            LIMIT 1
+        `).get(deps.tenantId, normalizedWorkspaceId, preferred);
+        if (!existing?.id || existing.id === normalizedCurrentTaskId) {
+            persistTaskReferenceSequence(deps, normalizedWorkspaceId, preferred);
+            return preferred;
+        }
+    }
+    return allocateNextTaskReferenceNumber(deps, normalizedWorkspaceId, normalizedCurrentTaskId || undefined);
+}
+export function getTaskByReferenceNumber(deps, referenceNumber, workspaceId) {
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return null;
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const row = deps.db.prepare(`
+        SELECT * FROM tasks
+        WHERE tenant_id = ? AND workspace_id = ? AND reference_number = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber);
+    if (!row)
+        return null;
+    return deps.rowToTask(row);
+}
+export function getTaskByLocalReferenceNumber(deps, referenceNumber, workspaceId) {
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return null;
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const row = deps.db.prepare(`
+        SELECT * FROM tasks
+        WHERE tenant_id = ? AND workspace_id = ? AND local_reference_number = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber);
+    if (!row)
+        return null;
+    return deps.rowToTask(row);
+}
+export function resolveTaskIdentifier(deps, value, workspaceId) {
+    const normalizedValue = String(value || '').trim();
+    if (!normalizedValue)
+        return null;
+    const referenceNumber = parseTaskReference(normalizedValue);
+    if (referenceNumber) {
+        const exactReferenceMatch = getTaskByReferenceNumber(deps, referenceNumber, workspaceId);
+        if (exactReferenceMatch)
+            return exactReferenceMatch;
+    }
+    const localReferenceNumber = parseLocalTaskReference(normalizedValue);
+    if (localReferenceNumber) {
+        const exactLocalReferenceMatch = getTaskByLocalReferenceNumber(deps, localReferenceNumber, workspaceId);
+        if (exactLocalReferenceMatch)
+            return exactLocalReferenceMatch;
+    }
+    return deps.getTask(normalizedValue, workspaceId);
+}
+export function deriveTaskReferenceLabel(task) {
+    return task.referenceNumber
+        ? `T-${task.referenceNumber}`
+        : formatLocalTaskReference(task.localReferenceNumber);
+}

package/dist/core/types.d.ts

@@ -27,6 +27,7 @@ export type TaskAssignee = string;
 export interface TaskItem {
     id: string;
     referenceNumber?: number | null;
+    localReferenceNumber?: number | null;
     referenceLabel?: string;
     title: string;
     description: string | null;
@@ -330,6 +331,7 @@ export interface UserIdentityRecord {
     userId: string;
     email: string;
     displayName?: string | null;
+    avatarUrl?: string | null;
     systemRole?: SystemRole;
     betaAccess?: boolean;
 }

package/dist/hooks/tasks/useTaskFormActions.js

@@ -130,6 +130,9 @@ export function useTaskFormActions(input) {
             if (!editingTaskId || attachmentsDirty) {
                 body.attachments = attachments;
             }
+            if (editingTaskId) {
+                body.saveSource = source;
+            }
             const res = await fetch(url, {
                 method,
                 headers: { 'Content-Type': 'application/json' },

package/dist/hooks/useTaskData.js

@@ -45,6 +45,16 @@ export function useTaskData({ tasks, archivedTasks, setTasks, setArchivedTasks,
     const getTaskRevisionKey = useCallback((task) => {
         return `${task.updatedAt || task.createdAt || ''}|${task.status}|${task.priority}|${task.title}`;
     }, []);
+    const isExpectedAbortFailure = useCallback((error, signal) => {
+        if (!signal.aborted)
+            return false;
+        if (error === signal.reason)
+            return true;
+        if (error instanceof DOMException) {
+            return error.name === 'AbortError';
+        }
+        return String(error?.name || '').toLowerCase() === 'aborterror';
+    }, []);
     // === SECTION: Recently Changed ===
     const [recentlyChangedTaskIds, setRecentlyChangedTaskIds] = useState([]);
     const highlightTimersRef = useRef(new Map());
@@ -137,18 +147,16 @@ export function useTaskData({ tasks, archivedTasks, setTasks, setArchivedTasks,
             }
         }
         catch (err) {
-            const isAbortError = err instanceof DOMException
-                ? err.name === 'AbortError'
-                : String(err?.name || '').toLowerCase() === 'aborterror';
-            if (isAbortError)
+            if (isExpectedAbortFailure(err, abortController.signal))
                 return;
             console.error('[Taskforce] Failed to fetch tasks:', err);
         }
         finally {
-            if (tasksAbortRef.current === abortController) {
+            const isCurrentRequest = tasksAbortRef.current === abortController;
+            if (isCurrentRequest) {
                 tasksAbortRef.current = null;
             }
-            if (!isSilent)
+            if (!isSilent && isCurrentRequest)
                 setLoadingTasks(false);
         }
     }, [
@@ -186,10 +194,7 @@ export function useTaskData({ tasks, archivedTasks, setTasks, setArchivedTasks,
             }
         }
         catch (err) {
-            const isAbortError = err instanceof DOMException
-                ? err.name === 'AbortError'
-                : String(err?.name || '').toLowerCase() === 'aborterror';
-            if (isAbortError)
+            if (isExpectedAbortFailure(err, abortController.signal))
                 return;
             console.error('[Taskforce] Failed to fetch archive:', err);
         }
@@ -198,7 +203,7 @@ export function useTaskData({ tasks, archivedTasks, setTasks, setArchivedTasks,
                 archiveAbortRef.current = null;
             }
         }
-    }, [getCurrentWorkspaceId, setArchivedTasks, shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls]);
+    }, [getCurrentWorkspaceId, isExpectedAbortFailure, setArchivedTasks, shouldDeferProtectedApiCalls, shouldBlockProtectedApiCalls]);
     const refreshTaskCollections = useCallback(async (options) => {
         const isSilent = options?.isSilent !== false;
         const ignoreAuthGuard = options?.ignoreAuthGuard === true;

package/dist/hooks/useTaskData.test.js

@@ -23,6 +23,46 @@ function makeAbortableRequest(payload) {
         }
     };
 }
+function makeAbortableRequestRejectingWithReason(payload) {
+    let rejectRequest = null;
+    let resolveRequest = null;
+    const promise = new Promise((resolve, reject) => {
+        resolveRequest = resolve;
+        rejectRequest = reject;
+    });
+    return {
+        promise,
+        attach(signal) {
+            signal?.addEventListener('abort', () => {
+                rejectRequest?.(signal.reason);
+            }, { once: true });
+            queueMicrotask(() => {
+                if (!signal?.aborted) {
+                    resolveRequest?.(makeAbortableFetchResponse(payload));
+                }
+            });
+        }
+    };
+}
+function makeControlledAbortableRequest(payload) {
+    let rejectRequest = null;
+    let resolveRequest = null;
+    const promise = new Promise((resolve, reject) => {
+        rejectRequest = reject;
+        resolveRequest = () => resolve(makeAbortableFetchResponse(payload));
+    });
+    return {
+        promise,
+        resolve() {
+            resolveRequest?.();
+        },
+        attach(signal) {
+            signal?.addEventListener('abort', () => {
+                rejectRequest?.(new DOMException('Aborted', 'AbortError'));
+            }, { once: true });
+        }
+    };
+}
 describe('useTaskData', () => {
     beforeEach(() => {
         vi.stubGlobal('fetch', vi.fn());
@@ -116,4 +156,91 @@ describe('useTaskData', () => {
         expect(requestSignals[0]?.aborted).toBe(true);
         expect(requestSignals[1]?.aborted).toBe(false);
     });
+    it('does not log an error when an archive request is aborted with a string reason', async () => {
+        const firstRequest = makeAbortableRequestRejectingWithReason({ archived: [] });
+        const secondRequest = makeAbortableRequestRejectingWithReason({ archived: [] });
+        const fetchMock = vi.mocked(fetch);
+        const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        let requestCount = 0;
+        fetchMock.mockImplementation((_input, init) => {
+            const signal = init?.signal;
+            requestCount += 1;
+            if (requestCount === 1) {
+                firstRequest.attach(signal);
+                return firstRequest.promise;
+            }
+            secondRequest.attach(signal);
+            return secondRequest.promise;
+        });
+        const { result } = renderHook(() => useTaskData({
+            tasks: [],
+            archivedTasks: [],
+            setTasks: vi.fn(),
+            setArchivedTasks: vi.fn(),
+            setLoadingTasks: vi.fn(),
+            getCurrentWorkspaceId: () => 'workspace-1',
+            workspaceResetKey: 'workspace-1',
+            shouldDeferProtectedApiCalls: false,
+            shouldBlockProtectedApiCalls: false,
+            handleUnauthorized: vi.fn(),
+            authRequiredForApi: false
+        }));
+        let firstPromise;
+        let secondPromise;
+        await act(async () => {
+            firstPromise = result.current.fetchArchive(true);
+            secondPromise = result.current.fetchArchive(true);
+            await secondPromise;
+            await firstPromise;
+        });
+        expect(consoleErrorSpy).not.toHaveBeenCalledWith('[Taskforce] Failed to fetch archive:', 'superseded');
+        expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+    it('keeps loading active until the replacement tasks request finishes', async () => {
+        const firstRequest = makeControlledAbortableRequest({ tasks: [] });
+        const secondRequest = makeControlledAbortableRequest({ tasks: [] });
+        const fetchMock = vi.mocked(fetch);
+        const setLoadingTasks = vi.fn();
+        let requestCount = 0;
+        fetchMock.mockImplementation((_input, init) => {
+            const signal = init?.signal;
+            requestCount += 1;
+            if (requestCount === 1) {
+                firstRequest.attach(signal);
+                return firstRequest.promise;
+            }
+            secondRequest.attach(signal);
+            return secondRequest.promise;
+        });
+        const { result } = renderHook(() => useTaskData({
+            tasks: [],
+            archivedTasks: [],
+            setTasks: vi.fn(),
+            setArchivedTasks: vi.fn(),
+            setLoadingTasks,
+            getCurrentWorkspaceId: () => 'workspace-1',
+            workspaceResetKey: 'workspace-1',
+            shouldDeferProtectedApiCalls: false,
+            shouldBlockProtectedApiCalls: false,
+            handleUnauthorized: vi.fn(),
+            authRequiredForApi: false
+        }));
+        let firstPromise;
+        let secondPromise;
+        await act(async () => {
+            firstPromise = result.current.fetchTasks(false);
+            secondPromise = result.current.fetchTasks(false);
+            await Promise.resolve();
+        });
+        expect(setLoadingTasks).toHaveBeenNthCalledWith(1, true);
+        expect(setLoadingTasks).toHaveBeenNthCalledWith(2, true);
+        expect(setLoadingTasks).toHaveBeenCalledTimes(2);
+        await act(async () => {
+            secondRequest.resolve();
+            await secondPromise;
+            await firstPromise;
+        });
+        expect(setLoadingTasks).toHaveBeenLastCalledWith(false);
+        expect(setLoadingTasks).toHaveBeenCalledTimes(3);
+    });
 });

package/dist/hooks/useTaskforce.d.ts

@@ -117,8 +117,10 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     authRequiredForApi: boolean;
     authBlocked: boolean;
     isAuthenticated: boolean;
+    authUserId: string;
     authUserEmail: string;
     authUserDisplayName: string;
+    authUserAvatarUrl: string;
     authWorkspaceId: string;
     userGlobalSyncStatus: "error" | "idle" | "syncing" | "disconnected";
     workspaceLastPullAt: string | null;
@@ -250,6 +252,8 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
     }>;
     updateCurrentUserProfile: (input: {
         displayName: string;
+        avatarDraftId?: string | null;
+        clearAvatar?: boolean;
     }) => Promise<{
         success: boolean;
         error?: string;
@@ -258,6 +262,7 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
             userId: string;
             email: string;
             displayName: string | null;
+            avatarUrl: string | null;
         };
     }>;
     requestEmailVerification: (email: string) => Promise<{

package/dist/hooks/useTaskforce.js

@@ -45,7 +45,7 @@ import { cloneDefaultWorkflowDefinitions } from '../shared/workflowDefaults.js';
 import { resolveClientDeploymentConfig } from '../config/clientDeployment';
 import { resolveTaskforceMcpBaseUrlFromBaseUrl } from '../config/cloudEnvironment';
 import { createDefaultAssigneeOptions, createWorkspaceAssigneeOptions, mergeAssigneeOptions } from '../utils/assignees';
-import { persistLocalMutationActorUserId } from '../utils/taskforceApiClient';
+import { persistLocalMutationActorUserId, readLocalMutationActorUserId } from '../utils/taskforceApiClient';
 import { useSyncOrchestrator } from './useSyncOrchestrator';
 import { useRealtimeSync } from './useRealtimeSync';
 import { useUiNotice } from './ui/useUiNotice';
@@ -129,8 +129,6 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 const workspaceMode = workspaceModeRaw === 'single-local' || workspaceModeRaw === 'multi-cloud'
                     ? workspaceModeRaw
                     : (runtimeModeHint === 'cloud' ? 'multi-cloud' : 'single-local');
-                const authSourceRaw = String(cfg.authSource || '').trim().toLowerCase();
-                const authSource = authSourceRaw === 'local' ? 'local' : 'cloud';
                 setRuntimeConfigOverride({
                     cloudEnvironment: typeof cfg.cloudEnvironment === 'string'
                         ? String(cfg.cloudEnvironment).trim().toLowerCase()
@@ -142,7 +140,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                     cloudAuthBaseUrl: normalizeBaseUrl(cfg.cloudAuthBaseUrl),
                     wsBaseUrl: normalizeBaseUrl(cfg.wsBaseUrl),
                     cloudAuthViaLocalProxy: Boolean(cfg.cloudAuthViaLocalProxy),
-                    authSource,
+                    authSource: 'cloud',
                     workspaceMode,
                     workspaceSwitchingEnabled: typeof cfg.workspaceSwitchingEnabled === 'boolean'
                         ? Boolean(cfg.workspaceSwitchingEnabled)
@@ -182,8 +180,10 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         || '';
     const explicitConfiguredCloudAuthBaseUrl = propCloudAuthBaseUrl || envCloudAuthBaseUrl || envBaseUrl;
     const runtimeResolvedCloudAuthBaseUrl = runtimeConfigOverride.cloudAuthBaseUrl || runtimeConfigOverride.baseUrl;
-    const normalizedCloudAuthBaseUrl = (explicitConfiguredCloudAuthBaseUrl
-        || runtimeResolvedCloudAuthBaseUrl
+    const preferredCloudAuthBaseUrl = isLoopbackHost
+        ? (runtimeResolvedCloudAuthBaseUrl || explicitConfiguredCloudAuthBaseUrl)
+        : (explicitConfiguredCloudAuthBaseUrl || runtimeResolvedCloudAuthBaseUrl);
+    const normalizedCloudAuthBaseUrl = (preferredCloudAuthBaseUrl
         || normalizedApiBaseUrl
         || defaultCloudAuthBaseUrl).trim().replace(/\/+$/, '');
     const inferredCloudMcpBaseUrl = normalizeBaseUrl(resolveTaskforceMcpBaseUrlFromBaseUrl(runtimeConfigOverride.cloudMcpBaseUrl
@@ -208,6 +208,10 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     const shouldGateProtectedApiCalls = shouldProbeCloudAuth && !authOnlyCloudMode;
     const cloudAuthConfigured = Boolean(normalizedCloudAuthBaseUrl || normalizedApiBaseUrl || isCloudHost);
     const initialRuntimeMode = isCloudHost ? 'cloud' : 'local';
+    const optimisticLocalAuthUserId = initialRuntimeMode === 'local' && isLoopbackHost && cloudAuthConfigured
+        ? readLocalMutationActorUserId()
+        : '';
+    const hasOptimisticLocalAuth = optimisticLocalAuthUserId.length > 0;
     const resolveApiUrl = useCallback((path) => {
         if (!path)
             return path;
@@ -310,11 +314,12 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         : runtimeContractFallback.workspaceSwitchingEnabled;
     const [authRequiredForApi, setAuthRequiredForApi] = useState(false);
     const [authBlocked, setAuthBlocked] = useState(false);
-    const [isAuthenticated, setIsAuthenticated] = useState(false);
-    const [authUserId, setAuthUserId] = useState('anonymous');
+    const [isAuthenticated, setIsAuthenticated] = useState(hasOptimisticLocalAuth);
+    const [authUserId, setAuthUserId] = useState(hasOptimisticLocalAuth ? optimisticLocalAuthUserId : 'anonymous');
     const [authWorkspaceId, setAuthWorkspaceId] = useState('');
     const [authUserEmail, setAuthUserEmail] = useState('');
     const [authUserDisplayName, setAuthUserDisplayName] = useState('');
+    const [authUserAvatarUrl, setAuthUserAvatarUrl] = useState('');
     const [hasBetaAccess, setHasBetaAccess] = useState(true);
     const [hydratedWorkspaceRole, setHydratedWorkspaceRole] = useState(null);
     const [currentWorkspaceId, setCurrentWorkspaceId] = useState(() => {
@@ -333,13 +338,13 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     const [availableWorkspaces, setAvailableWorkspaces] = useState([]);
     const [assigneeOptions, setAssigneeOptions] = useState(() => createDefaultAssigneeOptions());
     const [workspaceBootstrapPending, setWorkspaceBootstrapPending] = useState(false);
-    const [authSessionResolved, setAuthSessionResolved] = useState(false);
+    const [authSessionResolved, setAuthSessionResolved] = useState(hasOptimisticLocalAuth);
     const [bootstrapPhase, setBootstrapPhase] = useState('idle');
     const [bootstrapError, setBootstrapError] = useState(null);
     const [bootstrapStartedAt, setBootstrapStartedAt] = useState(null);
     const authSessionRequestRef = useRef(null);
     const authSessionLastCheckedAtRef = useRef(0);
-    const authSessionLastResultRef = useRef(false);
+    const authSessionLastResultRef = useRef(hasOptimisticLocalAuth);
     const currentWorkspaceIdRef = useRef(currentWorkspaceId);
     const explicitWorkspaceSelectionRef = useRef(null);
     const workspaceTransitionEpochRef = useRef(0);
@@ -622,6 +627,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         setIsAuthenticated(false);
         setAuthUserEmail('');
         setAuthUserDisplayName('');
+        setAuthUserAvatarUrl('');
         setError(AUTH_REQUIRED_ERROR);
     }, [AUTH_REQUIRED_ERROR, runtimeMode]);
     // === SECTION: Task Data ===
@@ -822,6 +828,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             persistLocalMutationActorUserId(null);
             setAuthUserEmail('');
             setAuthUserDisplayName('');
+            setAuthUserAvatarUrl('');
             setUserGlobalSyncStatus('disconnected');
             setUserGlobalSyncError(null);
             setHasBetaAccess(true);
@@ -881,6 +888,9 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 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));
@@ -892,6 +902,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 }
                 setAuthUserEmail(authenticated ? userEmail : '');
                 setAuthUserDisplayName(authenticated ? userDisplayName : '');
+                setAuthUserAvatarUrl(authenticated ? userAvatarUrl : '');
                 if (authenticated) {
                     setError((prev) => prev === AUTH_REQUIRED_ERROR ? '' : prev);
                 }
@@ -1769,7 +1780,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 if (currentMemberRole === 'owner' || currentMemberRole === 'admin' || currentMemberRole === 'member' || currentMemberRole === 'read-only') {
                     setHydratedWorkspaceRole(currentMemberRole);
                 }
-                else if (!workspaceSwitchingEnabled) {
+                else if (!workspaceSwitchingEnabled && users.length === 0) {
                     setHydratedWorkspaceRole(null);
                 }
                 const workspaceMemberCandidates = users
@@ -1793,7 +1804,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                     candidate
                 ])).values()).filter((candidate) => String(candidate.userId || '').trim().length > 0);
             }
-            else if (!workspaceSwitchingEnabled) {
+            else if (!workspaceSwitchingEnabled && !fallbackCandidates.length) {
                 setHydratedWorkspaceRole(null);
             }
             const mergedOptions = mergeAssigneeOptions([
@@ -2233,6 +2244,8 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             return { success: false, error: 'Cloud auth endpoint is not configured.' };
         }
         const trimmedDisplayName = String(input.displayName || '').trim();
+        const trimmedAvatarDraftId = typeof input.avatarDraftId === 'string' ? input.avatarDraftId.trim() : '';
+        const shouldClearAvatar = input.clearAvatar === true;
         if (!trimmedDisplayName) {
             return { success: false, error: 'Display name is required.' };
         }
@@ -2241,7 +2254,11 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 credentials: 'include',
-                body: JSON.stringify({ displayName: trimmedDisplayName })
+                body: JSON.stringify({
+                    displayName: trimmedDisplayName,
+                    ...(trimmedAvatarDraftId ? { avatarDraftId: trimmedAvatarDraftId } : {}),
+                    ...(shouldClearAvatar ? { clearAvatar: true } : {})
+                })
             });
             const data = await res.json().catch(() => ({}));
             if (!res.ok || !data?.success) {
@@ -2250,9 +2267,11 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             const profile = {
                 userId: typeof data?.profile?.userId === 'string' ? data.profile.userId : authUserId,
                 email: typeof data?.profile?.email === 'string' ? data.profile.email : authUserEmail,
-                displayName: typeof data?.profile?.displayName === 'string' ? data.profile.displayName : null
+                displayName: typeof data?.profile?.displayName === 'string' ? data.profile.displayName : null,
+                avatarUrl: typeof data?.profile?.avatarUrl === 'string' ? data.profile.avatarUrl : null
             };
             setAuthUserDisplayName(profile.displayName || '');
+            setAuthUserAvatarUrl(profile.avatarUrl || '');
             return { success: true, profile };
         }
         catch {
@@ -2505,13 +2524,20 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             // no-op
         }
         finally {
+            authSessionRequestRef.current = null;
+            authSessionLastResultRef.current = false;
+            authSessionLastCheckedAtRef.current = Date.now();
             setIsAuthenticated(false);
+            setAuthSessionResolved(true);
             setAuthUserId('anonymous');
+            setAuthWorkspaceId('');
             persistLocalMutationActorUserId(null);
             setAuthUserEmail('');
             setAuthUserDisplayName('');
+            setAuthUserAvatarUrl('');
             setUserGlobalSyncStatus('disconnected');
             setUserGlobalSyncError(null);
+            setHasBetaAccess(true);
             setAuthBlocked(runtimeMode === 'cloud' && authRequiredForApi);
             setCurrentWorkspaceId((prev) => {
                 const existing = String(prev || '').trim();
@@ -2527,11 +2553,31 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             });
             setAvailableWorkspaces([]);
             workspaceListHydratedRef.current = false;
+            setHydratedWorkspaceRole(null);
+            if (runtimeMode === 'local') {
+                await Promise.allSettled([
+                    fetchConfig({ ignoreAuthGuard: true }),
+                    fetchTasks(true, { ignoreAuthGuard: true }),
+                    fetchPlanningEntities({ ignoreAuthGuard: true }),
+                    fetchReferenceData({ ignoreAuthGuard: true, force: true })
+                ]);
+                return;
+            }
             setTasks([]);
             setInitiatives([]);
             setWorkstreams([]);
         }
-    }, [authRequiredForApi, resolveCloudAuthUrl, cloudAuthConfigured, workspaceSelectionScope, runtimeMode]);
+    }, [
+        authRequiredForApi,
+        resolveCloudAuthUrl,
+        cloudAuthConfigured,
+        workspaceSelectionScope,
+        runtimeMode,
+        fetchConfig,
+        fetchPlanningEntities,
+        fetchReferenceData,
+        fetchTasks
+    ]);
     const createInitiativeFromTemplate = useCallback(async (payload) => {
         try {
             const res = await fetch('/api/taskforce/initiative-templates/create', {
@@ -3456,8 +3502,10 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         authRequiredForApi,
         authBlocked,
         isAuthenticated,
+        authUserId,
         authUserEmail,
         authUserDisplayName,
+        authUserAvatarUrl,
         authWorkspaceId,
         userGlobalSyncStatus,
         workspaceLastPullAt,