@taskforcehq/taskforce 0.3.303 → 0.3.304

package/dist/core/TaskAuditTimeline.test.js

@@ -92,7 +92,7 @@ describe('TaskforceCore task audit timeline', () => {
             cleanup();
         }
     });
-    it('suppresses task events for autosave-style updates when skipTaskEvents is true', () => {
+    it('suppresses task events when skipTaskEvents is explicitly true', () => {
         const { core, cleanup } = makeCore();
         try {
             const task = core.createTask({ title: 'Autosave task', createdBy: 'user' }, { workspaceId: 'workspace-a', actorRef: 'user' });
@@ -110,6 +110,57 @@ describe('TaskforceCore task audit timeline', () => {
             cleanup();
         }
     });
+    it('suppresses title and description autosave events while preserving the saved task content', () => {
+        const { core, cleanup } = makeCore();
+        try {
+            const task = core.createTask({ title: 'Autosave title task', createdBy: 'user' }, { workspaceId: 'workspace-a', actorRef: 'user' });
+            core.updateTask(task.id, {
+                title: 'Autosave title task updated',
+                description: 'Draft body'
+            }, 'workspace-a', {
+                actorRef: 'user',
+                saveSource: 'autosave'
+            });
+            const events = core.listTaskEvents(task.id, 'workspace-a');
+            const hydrated = core.getTask(task.id, 'workspace-a');
+            expect(events.map((event) => event.action)).toEqual(['task-created']);
+            expect(hydrated?.title).toBe('Autosave title task updated');
+            expect(hydrated?.description).toBe('Draft body');
+            expect(hydrated?.activity?.some((item) => item.type === 'event' && item.event.action === 'task-updated')).toBe(false);
+        }
+        finally {
+            cleanup();
+        }
+    });
+    it('keeps meaningful autosave updates in the activity feed while filtering noisy text changes', () => {
+        const { core, cleanup } = makeCore();
+        try {
+            const task = core.createTask({ title: 'Autosave assignee task', createdBy: 'user' }, { workspaceId: 'workspace-a', actorRef: 'user' });
+            core.updateTask(task.id, {
+                title: 'Autosave assignee task updated',
+                assignee: 'member-1'
+            }, 'workspace-a', {
+                actorRef: 'user',
+                saveSource: 'autosave'
+            });
+            const assignmentEvent = core.listTaskEvents(task.id, 'workspace-a').find((event) => event.action === 'task-updated' && event.details?.changes?.assignee);
+            expect(assignmentEvent).toEqual(expect.objectContaining({
+                action: 'task-updated',
+                details: {
+                    changes: {
+                        assignee: {
+                            from: 'unassigned',
+                            to: 'member-1',
+                        },
+                    },
+                },
+            }));
+            expect(assignmentEvent?.details?.changes?.title).toBeUndefined();
+        }
+        finally {
+            cleanup();
+        }
+    });
     it('captures assignment changes in the core task update event details', () => {
         const { core, cleanup } = makeCore();
         try {

package/dist/core/Taskforce.d.ts

@@ -3,6 +3,8 @@ import { WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
 import { type SyncEventInput } from './SyncReconciliationService.js';
 import { type FirstClassTaxonomyDisplayLabels, type WorkspaceTaxonomyState } from '../shared/taxonomyState.js';
 import { type AiProfileSurfaceType } from '../shared/aiProfileSurfaceType.js';
+import type { TaskActor } from '../shared/taskActor.js';
+export type { TaskActor } from '../shared/taskActor.js';
 export type { WorkspaceDeletedAssetRecord, WorkspaceDeleteSummary } from './types.js';
 import type { GlobalTaskforceSettings, UserGlobalSyncSettings, WorkspaceDeleteSummary } from './types.js';
 import type { AnnotatedAttachmentAnnotation, AnnotatedAttachmentPayload, AnnotatedAttachmentSession, AnnotatedAttachmentSessionRecord } from '../annotatedAttachments/types.js';
@@ -73,16 +75,6 @@ export interface DeletedTaskRecord {
 }
 export type TaskStatus = 'task' | 'on-hold' | 'in-progress' | 'review' | 'done' | 'cancelled';
 export type TaskAssignee = string;
-export interface TaskActor {
-    id: string;
-    kind: 'human' | 'ai';
-    label: string;
-    username: string;
-    icon: string;
-    color: string;
-    isNamed: boolean;
-    meta?: Record<string, unknown>;
-}
 export interface TaskItem {
     id: string;
     referenceNumber?: number | null;
@@ -755,6 +747,9 @@ export interface TaskforceSyncCapable {
         workspaceId?: string | null;
         includeDeleted?: boolean;
     }): AnnotatedAttachmentSessionRecord[];
+    listTaskEventsForSync(input: {
+        workspaceId?: string | null;
+    }): TaskEvent[];
     upsertAiProfileForSync(profile: AiProfileRecord): AiProfileRecord;
     replaceWorkspaceUsersForSync(input: {
         workspaceId: string;
@@ -765,6 +760,7 @@ export interface TaskforceSyncCapable {
     upsertDocumentReviewSessionForSync(session: DocumentReviewSessionRecord): DocumentReviewSessionRecord;
     upsertDocumentReviewCommentForSync(comment: DocumentReviewCommentSyncRecord): DocumentReviewCommentSyncRecord;
     upsertAnnotatedAttachmentSessionForSync(session: AnnotatedAttachmentSessionRecord): AnnotatedAttachmentSessionRecord;
+    upsertTaskEventForSync(event: TaskEvent): TaskEvent;
     deleteDocumentReviewSessionForSync(input: {
         workspaceId?: string | null;
         sessionId: string;
@@ -847,6 +843,7 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     private areTaskEventValuesEqual;
     private normalizeTaskEventValue;
     private buildTaskUpdateChanges;
+    private filterAutosaveTaskEventChanges;
     private normalizeTaxonomyToken;
     private normalizeStatusValue;
     private sanitizeAssignee;
@@ -893,16 +890,18 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         effectiveAt?: string | null;
         effectiveUntil?: string | null;
         billingMirrorPlanId?: string | null;
-        source: 'registration' | 'checkout-start' | 'checkout-confirm' | 'stripe-webhook' | 'backfill' | 'legacy-plan-mode' | 'admin' | 'system';
+        source: 'registration' | 'invite-accept' | 'checkout-start' | 'checkout-confirm' | 'stripe-webhook' | 'backfill' | 'legacy-plan-mode' | 'admin' | 'system';
         updatedBy: string;
         createdAt?: string | null;
         updatedAt?: string | null;
     }): import("./types.js").AccountEntitlementSnapshot;
     private resolveWorkspaceLimitForUser;
     private resolveRegistrationOnboardingOutcome;
+    private ensureDefaultOnboardingEntitlement;
     createUserBillingRecord(userId: string, options?: {
         entitlementState?: string;
         planId?: string | null;
+        effectiveUntil?: string | null;
     }): void;
     getUserEntitlement(userId: string): {
         entitlementState: string;
@@ -1268,6 +1267,7 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     upsertDocumentReviewSessionForSync(session: DocumentReviewSessionRecord): DocumentReviewSessionRecord;
     upsertDocumentReviewCommentForSync(comment: DocumentReviewCommentSyncRecord): DocumentReviewCommentSyncRecord;
     upsertAnnotatedAttachmentSessionForSync(session: AnnotatedAttachmentSessionRecord): AnnotatedAttachmentSessionRecord;
+    upsertTaskEventForSync(event: TaskEvent): TaskEvent;
     deleteDocumentReviewSessionForSync(input: {
         workspaceId?: string | null;
         sessionId: string;
@@ -1668,6 +1668,9 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     updateWorkspaceUserRole(userId: string, workspaceId: string, role: AccessRole): boolean;
     getTask(id: string, workspaceId?: string): TaskItem | null;
     listTaskEvents(taskId: string, workspaceId?: string): TaskEvent[];
+    listTaskEventsForSync(input: {
+        workspaceId?: string | null;
+    }): TaskEvent[];
     getScheduleBoard(weekKey: string, showWeekends?: boolean, workspaceId?: string): ScheduleBoardResult;
     updateTaskSchedule(id: string, input: {
         scheduledDate: string | null;
@@ -1699,6 +1702,7 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         syncUpdatedAt?: string;
         actorRef?: string;
         skipTaskEvents?: boolean;
+        saveSource?: 'manual' | 'autosave';
     }): TaskItem | null;
     addComment(id: string, text: string, author: string, workspaceId?: string, options?: {
         persistBackup?: boolean;

package/dist/core/Taskforce.js

@@ -9,7 +9,7 @@ import { WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
 import { AuthTokenService } from './AuthTokenService.js';
 import { getAiProfileByTokenService, listAiProfilesService, mergeAiProfilesService, resolveAiProfileService, upsertAiProfileForSyncService, } from './AiProfileService.js';
 import { syncCanonicalTaskAttachmentLinksService, } from './AttachmentLinkService.js';
-import { addTaskEventService, buildTaskActivityService, listTaskEventsInternalService, replaceTaskCommentsService, replaceTaskEventsService, } from './TaskActivityService.js';
+import { addTaskEventService, buildTaskActivityService, listTaskEventsInternalService, listWorkspaceTaskEventsService, replaceTaskCommentsService, replaceTaskEventsService, upsertTaskEventForSyncService, } from './TaskActivityService.js';
 import { addDeletedTaskRecordService, getDeletedTaskService, listDeletedTasksService, mapDeletedTaskRowService, normalizeTaskSnapshotForRestoreService, pruneDeletedTasksService, purgeExpiredDeletedTasksService, } from './DeletedTaskLifecycleService.js';
 import { applyWorkspaceSyncSnapshotService, deleteDocumentWatermarkService, getDocumentWatermarkService, listTasksForSyncService, listWorkspaceSyncDeletesSinceService, readPushIdempotencyService, recordSyncEventService, upsertDocumentWatermarkService, writePushIdempotencyService, } from './SyncReconciliationService.js';
 import { getGlobalSettingsService, hasPersistedGlobalSettingsService, readGlobalConfigService, updateGlobalSettingsService, writeGlobalConfigService, } from './GlobalSettingsService.js';
@@ -666,6 +666,9 @@ export class TaskforceCore {
         }
         return changes;
     }
+    filterAutosaveTaskEventChanges(changes) {
+        return Object.fromEntries(Object.entries(changes).filter(([field]) => field !== 'title' && field !== 'description'));
+    }
     normalizeTaxonomyToken(value) {
         return String(value || '')
             .trim()
@@ -1217,6 +1220,29 @@ export class TaskforceCore {
     resolveRegistrationOnboardingOutcome(selectedPlanVersionIdRaw) {
         return this.planEntitlementService.resolveRegistrationOnboardingOutcome(selectedPlanVersionIdRaw);
     }
+    ensureDefaultOnboardingEntitlement(accountIdRaw, options) {
+        const accountId = String(accountIdRaw || '').trim();
+        if (!accountId) {
+            throw new TaskforceRuleError('accountId is required', 400, 'ACCOUNT_ID_REQUIRED');
+        }
+        if (this.hasAccountEntitlement(accountId)) {
+            return this.getAccountEntitlement(accountId);
+        }
+        const now = options?.now || new Date().toISOString();
+        const onboardingOutcome = this.resolveRegistrationOnboardingOutcome();
+        this.transitionCanonicalCommercialState({
+            accountId,
+            planVersionId: onboardingOutcome.planVersionId,
+            state: onboardingOutcome.commercialState,
+            effectiveAt: now,
+            billingMirrorPlanId: onboardingOutcome.planId,
+            source: options?.source || 'registration',
+            updatedBy: options?.updatedBy || 'registration',
+            createdAt: now,
+            updatedAt: now
+        });
+        return this.getAccountEntitlement(accountId);
+    }
     createUserBillingRecord(userId, options) {
         return this.planEntitlementService.createUserBillingRecord(userId, options);
     }
@@ -4841,6 +4867,9 @@ export class TaskforceCore {
             deletedAt: session.deletedAt,
         });
     }
+    upsertTaskEventForSync(event) {
+        return upsertTaskEventForSyncService(this.getTaskActivityServiceDeps(), event);
+    }
     deleteDocumentReviewSessionForSync(input) {
         const deps = this.getDocumentReviewServiceDeps();
         return deps.sessionStore.softDelete(input.sessionId, deps.normalizeWorkspaceId(input.workspaceId), input.deletedAt || undefined);
@@ -5795,6 +5824,11 @@ export class TaskforceCore {
                 updated_at = ?
             WHERE tenant_id = ? AND id = ?
         `).run(hashPassword(password), 'password', user.email, now, now, this.tenantId, consumed.userId);
+        this.ensureDefaultOnboardingEntitlement(consumed.userId, {
+            source: 'invite-accept',
+            updatedBy: 'invite-accept',
+            now
+        });
         return this.completeInviteWorkspaceActivation({
             userId: consumed.userId,
             workspaceId: inviteWorkspaceId
@@ -5953,6 +5987,10 @@ export class TaskforceCore {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
         return this.listTaskEventsInternal(taskId, normalizedWorkspaceId);
     }
+    listTaskEventsForSync(input) {
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(input.workspaceId || undefined);
+        return listWorkspaceTaskEventsService(this.getTaskActivityServiceDeps(), normalizedWorkspaceId);
+    }
     getScheduleBoard(weekKey, showWeekends = false, workspaceId) {
         const parsedWeek = this.parseIsoWeekKeyToDates(weekKey);
         if (!parsedWeek) {
@@ -6510,7 +6548,10 @@ export class TaskforceCore {
             if (!nextTask)
                 return null;
             if (options?.skipTaskEvents !== true) {
-                const changes = this.buildTaskUpdateChanges(existing, nextTask, patch);
+                const rawChanges = this.buildTaskUpdateChanges(existing, nextTask, patch);
+                const changes = options?.saveSource === 'autosave'
+                    ? this.filterAutosaveTaskEventChanges(rawChanges)
+                    : rawChanges;
                 if (Object.keys(changes).length > 0) {
                     let action = 'task-updated';
                     if (changes.status) {

package/dist/core/WorkspacePlanMode.test.js

@@ -23,6 +23,17 @@ function openCore(projectRoot) {
     core.upsertPlanCatalog({ planId: 'starter', displayName: 'Starter' });
     addFreeMapping('starter-v1');
     core.upsertPlanCatalog({ planId: 'starter', displayName: 'Starter', status: 'active' });
+    core.updatePlanVersion({
+        planId: 'starter',
+        versionNumber: 1,
+        seatLimit: 1
+    });
+    core.updatePlanVersionFeatures({
+        planVersionId: 'starter-v1',
+        features: [
+            { featureKey: 'workspace.switching', access: 'enabled' }
+        ]
+    });
     core.upsertPlanCatalog({ planId: 'collab', displayName: 'Collab' });
     addFreeMapping('collab-v1');
     core.upsertPlanCatalog({ planId: 'collab', displayName: 'Collab', status: 'active' });
@@ -214,4 +225,58 @@ describe('TaskforceCore account-level plan mode and invite revoke', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('grants the default onboarding entitlement to newly accepted invited accounts', () => {
+        const projectRoot = makeProjectRoot();
+        const core = openCore(projectRoot);
+        try {
+            core.updateGlobalSettings({
+                billing: {
+                    onboardingPolicy: {
+                        mode: 'auto_grant_free',
+                        planVersionId: 'starter-v1'
+                    }
+                }
+            });
+            core.createWorkspace({ workspaceId: 'workspace-invite', name: 'Invite Workspace' });
+            core.ensureBootstrapUserAccess({
+                userId: 'owner-user',
+                workspaceId: 'workspace-invite',
+                role: 'owner',
+                email: 'owner@example.com'
+            });
+            core.setUserAccountPlanMode('owner-user', 'team');
+            core.ensureBootstrapUserAccess({
+                userId: 'invited-user',
+                workspaceId: 'workspace-invite',
+                role: 'member',
+                email: 'invited@example.com'
+            });
+            core.setWorkspaceUserDisabled('invited-user', 'workspace-invite', true);
+            const db = core.db;
+            db.prepare(`
+                UPDATE workspace_memberships
+                SET status = 'invited'
+                WHERE tenant_id = ? AND user_id = ? AND workspace_id = ?
+            `).run('default', 'invited-user', 'workspace-invite');
+            const invite = core.requestInviteAcceptance({ userId: 'invited-user', workspaceId: 'workspace-invite' });
+            const accepted = core.acceptInviteWithToken({
+                token: String(invite.token),
+                password: 'Password123!'
+            });
+            expect(accepted.workspaceId).toBe('workspace-invite');
+            expect(core.hasAccountEntitlement('invited-user')).toBe(true);
+            expect(core.getAccountEntitlement('invited-user')).toEqual(expect.objectContaining({
+                planVersionId: 'starter-v1',
+                state: 'active'
+            }));
+            expect(core.getAccountAccessStatus('invited-user')).toEqual(expect.objectContaining({
+                gate: 'ok',
+                canAccessApp: true
+            }));
+        }
+        finally {
+            core.close();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
 });

package/dist/documentReviews/service.d.ts

@@ -1,4 +1,4 @@
-import type { TaskActor } from '../core/Taskforce.js';
+import type { TaskActor } from '../shared/taskActor.js';
 import type { WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
 import { DocumentReviewCommentStore } from './DocumentReviewCommentStore.js';
 import { DocumentReviewSessionStore } from './DocumentReviewSessionStore.js';

package/dist/documentReviews/types.d.ts

@@ -1,4 +1,4 @@
-import type { TaskActor } from '../core/Taskforce.js';
+import type { TaskActor } from '../shared/taskActor.js';
 export type DocumentReviewSessionStatus = 'open' | 'resolved';
 export type DocumentReviewAnchorKind = 'document' | 'quote' | 'line-range';
 export interface DocumentReviewDocumentAnchor {

package/dist/hooks/auth/useTaskforceAuthBootstrap.d.ts

@@ -0,0 +1,48 @@
+import { type MutableRefObject } from 'react';
+import { createDefaultAssigneeOptions } from '../../utils/assignees';
+export type BootstrapPhase = 'idle' | 'auth' | 'workspace' | 'config' | 'ready' | 'stalled';
+interface UseTaskforceAuthBootstrapArgs {
+    runtimeConfigReady: boolean;
+    shouldProbeCloudAuth: boolean;
+    authSessionResolved: boolean;
+    resolveCloudAuthUrl: (path: string) => string;
+    authOnlyCloudMode: boolean;
+    authRequiredError: string;
+    runtimeMode: 'local' | 'cloud';
+    workspaceSelectionScope: string;
+    markBootstrapPhase: (phase: Exclude<BootstrapPhase, 'stalled'>) => void;
+    markBootstrapStalled: (message: string) => void;
+    setRuntimeMode: (mode: 'local' | 'cloud') => void;
+    setAuthRequiredForApi: (value: boolean) => void;
+    setIsAuthenticated: (value: boolean) => void;
+    setAuthUserId: (value: string) => void;
+    setAuthWorkspaceId: (value: string) => void;
+    setAuthUserEmail: (value: string) => void;
+    setAuthUserDisplayName: (value: string) => void;
+    setAuthUserAvatarUrl: (value: string) => void;
+    setUserGlobalSyncStatus: (value: 'idle' | 'disconnected') => void;
+    setUserGlobalSyncError: (value: string | null) => void;
+    setHasBetaAccess: (value: boolean) => void;
+    setAvailableWorkspaces: (value: any[]) => void;
+    setHydratedWorkspaceRole: (value: any) => void;
+    setAssigneeOptions: (value: ReturnType<typeof createDefaultAssigneeOptions>) => void;
+    setAuthBlocked: (value: boolean) => void;
+    setAuthSessionResolved: (value: boolean) => void;
+    setError: (value: string | ((prev: string) => string)) => void;
+    applyResolvedWorkspaceId: (workspaceId: string, options?: {
+        preserveNonDefaultDefault?: boolean;
+    }) => void;
+    readPersistedWorkspaceId: (scope: string) => string;
+    authSessionRequestRef: MutableRefObject<Promise<boolean> | null>;
+    authSessionEpochRef: MutableRefObject<number>;
+    authSessionLastCheckedAtRef: MutableRefObject<number>;
+    authSessionLastResultRef: MutableRefObject<boolean>;
+    isLoopbackHost: boolean;
+    setAuthStateReadyRefs: (authenticated: boolean, authSessionResolved: boolean, authRequiredForApi: boolean) => void;
+}
+export declare function useTaskforceAuthBootstrap({ runtimeConfigReady, shouldProbeCloudAuth, authSessionResolved, resolveCloudAuthUrl, authOnlyCloudMode, authRequiredError, runtimeMode, workspaceSelectionScope, markBootstrapPhase, markBootstrapStalled, setRuntimeMode, setAuthRequiredForApi, setIsAuthenticated, setAuthUserId, setAuthWorkspaceId, setAuthUserEmail, setAuthUserDisplayName, setAuthUserAvatarUrl, setUserGlobalSyncStatus, setUserGlobalSyncError, setHasBetaAccess, setAvailableWorkspaces, setHydratedWorkspaceRole, setAssigneeOptions, setAuthBlocked, setAuthSessionResolved, setError, applyResolvedWorkspaceId, readPersistedWorkspaceId, authSessionRequestRef, authSessionEpochRef, authSessionLastCheckedAtRef, authSessionLastResultRef, isLoopbackHost, setAuthStateReadyRefs }: UseTaskforceAuthBootstrapArgs): {
+    checkAuthSession: (options?: {
+        force?: boolean;
+    }) => Promise<boolean>;
+};
+export {};

package/dist/hooks/auth/useTaskforceAuthBootstrap.js

@@ -0,0 +1,219 @@
+import { useCallback, useEffect } from 'react';
+import { createDefaultAssigneeOptions } from '../../utils/assignees';
+import { persistLocalMutationActorUserId, readLocalMutationActorUserId } from '../../utils/taskforceApiClient';
+export function useTaskforceAuthBootstrap({ runtimeConfigReady, shouldProbeCloudAuth, authSessionResolved, resolveCloudAuthUrl, authOnlyCloudMode, authRequiredError, runtimeMode, workspaceSelectionScope, markBootstrapPhase, markBootstrapStalled, setRuntimeMode, setAuthRequiredForApi, setIsAuthenticated, setAuthUserId, setAuthWorkspaceId, setAuthUserEmail, setAuthUserDisplayName, setAuthUserAvatarUrl, setUserGlobalSyncStatus, setUserGlobalSyncError, setHasBetaAccess, setAvailableWorkspaces, setHydratedWorkspaceRole, setAssigneeOptions, setAuthBlocked, setAuthSessionResolved, setError, applyResolvedWorkspaceId, readPersistedWorkspaceId, authSessionRequestRef, authSessionEpochRef, authSessionLastCheckedAtRef, authSessionLastResultRef, isLoopbackHost, setAuthStateReadyRefs }) {
+    const checkAuthSession = useCallback(async (options) => {
+        const force = options?.force === true;
+        markBootstrapPhase('auth');
+        if (!runtimeConfigReady) {
+            return authSessionLastResultRef.current;
+        }
+        if (!shouldProbeCloudAuth) {
+            setRuntimeMode('local');
+            setAuthRequiredForApi(false);
+            setIsAuthenticated(false);
+            setAuthUserId('anonymous');
+            setAuthWorkspaceId('');
+            persistLocalMutationActorUserId(null);
+            setAuthUserEmail('');
+            setAuthUserDisplayName('');
+            setAuthUserAvatarUrl('');
+            setUserGlobalSyncStatus('disconnected');
+            setUserGlobalSyncError(null);
+            setHasBetaAccess(true);
+            setAvailableWorkspaces([]);
+            setHydratedWorkspaceRole(null);
+            setAssigneeOptions(createDefaultAssigneeOptions());
+            setAuthBlocked(false);
+            setAuthSessionResolved(true);
+            setAuthStateReadyRefs(false, true, false);
+            authSessionLastResultRef.current = false;
+            authSessionLastCheckedAtRef.current = Date.now();
+            return false;
+        }
+        const sessionUrl = resolveCloudAuthUrl('/api/taskforce/auth/session');
+        const now = Date.now();
+        if (!force && authSessionRequestRef.current)
+            return authSessionRequestRef.current;
+        if (!force && authSessionResolved && (now - authSessionLastCheckedAtRef.current) < 1500) {
+            return authSessionLastResultRef.current;
+        }
+        const requestEpoch = ++authSessionEpochRef.current;
+        let request = null;
+        request = (async () => {
+            const abortController = new AbortController();
+            const timeoutId = typeof window !== 'undefined'
+                ? window.setTimeout(() => abortController.abort(), 8000)
+                : null;
+            const isStaleRequest = () => authSessionEpochRef.current !== requestEpoch;
+            try {
+                const res = await fetch(sessionUrl, {
+                    method: 'GET',
+                    credentials: 'include',
+                    mode: 'cors',
+                    signal: abortController.signal
+                });
+                if (isStaleRequest()) {
+                    return authSessionLastResultRef.current;
+                }
+                if (res.status === 429) {
+                    setAuthSessionResolved(true);
+                    setAuthStateReadyRefs(authSessionLastResultRef.current, true, false);
+                    return authSessionLastResultRef.current;
+                }
+                if (!res.ok) {
+                    if (isStaleRequest()) {
+                        return authSessionLastResultRef.current;
+                    }
+                    if (isLoopbackHost)
+                        persistLocalMutationActorUserId(null);
+                    setAuthSessionResolved(true);
+                    setAuthStateReadyRefs(false, true, false);
+                    authSessionLastResultRef.current = false;
+                    return false;
+                }
+                const data = await res.json();
+                if (isStaleRequest()) {
+                    return authSessionLastResultRef.current;
+                }
+                const required = Boolean(data.authRequiredForApi);
+                const authenticated = Boolean(data.authenticated);
+                const betaAccess = authenticated ? (data.betaAccess !== false) : true;
+                const workspaceId = typeof data.workspaceId === 'string' && data.workspaceId.trim().length > 0
+                    ? data.workspaceId.trim()
+                    : '';
+                const userId = typeof data.userId === 'string' && data.userId.trim().length > 0
+                    ? data.userId.trim()
+                    : 'anonymous';
+                const userEmail = typeof data.email === 'string' && data.email.trim().length > 0
+                    ? data.email.trim().toLowerCase()
+                    : '';
+                const userDisplayName = typeof data.displayName === 'string' ? data.displayName.trim() : '';
+                const userAvatarUrl = typeof data.avatarUrl === 'string' ? data.avatarUrl.trim() : '';
+                const isLocalRuntime = runtimeMode === 'local';
+                const keepLocalWorkspaceContext = runtimeMode === 'local' || authOnlyCloudMode;
+                const nextAuthRequiredForApi = authOnlyCloudMode ? false : (isLocalRuntime ? false : required);
+                setAuthRequiredForApi(nextAuthRequiredForApi);
+                setIsAuthenticated(authenticated);
+                setAuthUserId(authenticated ? userId : 'anonymous');
+                setAuthWorkspaceId(authenticated ? workspaceId : '');
+                if (isLoopbackHost)
+                    persistLocalMutationActorUserId(authenticated ? userId : null);
+                setAuthUserEmail(authenticated ? userEmail : '');
+                setAuthUserDisplayName(authenticated ? userDisplayName : '');
+                setAuthUserAvatarUrl(authenticated ? userAvatarUrl : '');
+                if (authenticated) {
+                    setError((prev) => prev === authRequiredError ? '' : prev);
+                }
+                setUserGlobalSyncStatus(authenticated ? 'idle' : 'disconnected');
+                setUserGlobalSyncError(null);
+                setHasBetaAccess(betaAccess);
+                if (!keepLocalWorkspaceContext) {
+                    applyResolvedWorkspaceId(workspaceId || readPersistedWorkspaceId(workspaceSelectionScope) || 'default', { preserveNonDefaultDefault: true });
+                }
+                setAuthBlocked(authOnlyCloudMode ? false : (isLocalRuntime ? false : (required && !authenticated)));
+                setAuthSessionResolved(true);
+                setAuthStateReadyRefs(authenticated, true, nextAuthRequiredForApi);
+                authSessionLastResultRef.current = authenticated;
+                if (authenticated)
+                    markBootstrapPhase('ready');
+                return authenticated;
+            }
+            catch {
+                if (isStaleRequest()) {
+                    return authSessionLastResultRef.current;
+                }
+                if (isLoopbackHost)
+                    persistLocalMutationActorUserId(null);
+                setAuthSessionResolved(true);
+                setAuthStateReadyRefs(false, true, false);
+                authSessionLastResultRef.current = false;
+                markBootstrapStalled('Unable to verify your session.');
+                return authSessionLastResultRef.current;
+            }
+            finally {
+                if (timeoutId !== null && typeof window !== 'undefined') {
+                    window.clearTimeout(timeoutId);
+                }
+                if (!isStaleRequest()) {
+                    authSessionLastCheckedAtRef.current = Date.now();
+                }
+                if (request && authSessionRequestRef.current === request) {
+                    authSessionRequestRef.current = null;
+                }
+            }
+        })();
+        authSessionRequestRef.current = request;
+        return request;
+    }, [
+        runtimeConfigReady,
+        shouldProbeCloudAuth,
+        authSessionResolved,
+        resolveCloudAuthUrl,
+        authOnlyCloudMode,
+        authRequiredError,
+        runtimeMode,
+        workspaceSelectionScope,
+        markBootstrapPhase,
+        markBootstrapStalled,
+        setRuntimeMode,
+        setAuthRequiredForApi,
+        setIsAuthenticated,
+        setAuthUserId,
+        setAuthWorkspaceId,
+        setAuthUserEmail,
+        setAuthUserDisplayName,
+        setAuthUserAvatarUrl,
+        setUserGlobalSyncStatus,
+        setUserGlobalSyncError,
+        setHasBetaAccess,
+        setAvailableWorkspaces,
+        setHydratedWorkspaceRole,
+        setAssigneeOptions,
+        setAuthBlocked,
+        setAuthSessionResolved,
+        setError,
+        applyResolvedWorkspaceId,
+        readPersistedWorkspaceId,
+        authSessionRequestRef,
+        authSessionEpochRef,
+        authSessionLastCheckedAtRef,
+        authSessionLastResultRef,
+        isLoopbackHost,
+        setAuthStateReadyRefs
+    ]);
+    const optimisticLocalAuthUserId = runtimeMode === 'local' && isLoopbackHost && shouldProbeCloudAuth
+        ? readLocalMutationActorUserId()
+        : '';
+    useEffect(() => {
+        if (optimisticLocalAuthUserId) {
+            setIsAuthenticated(true);
+            setAuthSessionResolved(true);
+            setAuthUserId(optimisticLocalAuthUserId);
+            setAuthStateReadyRefs(true, true, false);
+            authSessionLastResultRef.current = true;
+        }
+    }, [optimisticLocalAuthUserId, setAuthSessionResolved, setAuthStateReadyRefs, setAuthUserId, setIsAuthenticated, authSessionLastResultRef]);
+    useEffect(() => {
+        if (runtimeMode !== 'local' || !shouldProbeCloudAuth)
+            return;
+        if (typeof window === 'undefined')
+            return;
+        const recheck = () => { void checkAuthSession(); };
+        const onVisibilityChange = () => {
+            if (document.visibilityState === 'visible')
+                recheck();
+        };
+        window.addEventListener('focus', recheck);
+        window.addEventListener('online', recheck);
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        const intervalId = window.setInterval(recheck, 30_000);
+        return () => {
+            window.removeEventListener('focus', recheck);
+            window.removeEventListener('online', recheck);
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+            window.clearInterval(intervalId);
+        };
+    }, [runtimeMode, shouldProbeCloudAuth, checkAuthSession]);
+    return { checkAuthSession };
+}

package/dist/hooks/sync/auth.d.ts

@@ -0,0 +1,37 @@
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+interface CreateSyncAuthCoordinatorArgs {
+    currentWorkspaceId: string;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    clearWorkspaceRetry: () => void;
+    setWorkspaceSyncBusy: (value: boolean) => void;
+    setUserGlobalSyncStatus: (value: 'error') => void;
+    setUserGlobalSyncError: (value: string) => void;
+    setWorkspaceLastErrorMessage: (value: string) => void;
+    setWorkspaceLastErrorAt: (value: string) => void;
+    reportSyncEvent: (workspaceId: string, event: {
+        eventType: 'pull' | 'handshake' | 'bootstrap' | 'apply' | 'push';
+        status: 'success' | 'error';
+        statusCode?: number;
+        errorMessage?: string;
+    }) => void;
+    setAuthBlocked: (value: boolean) => void;
+    setIsAuthenticated: (value: boolean) => void;
+    checkAuthSession: () => Promise<boolean>;
+    ensureCloudWorkspaceReadyForSync: () => Promise<{
+        success: boolean;
+        statusCode?: number;
+        error?: string;
+        transient?: boolean;
+        retryAfterMs?: number;
+    }>;
+    scheduleWorkspaceSyncRetry: (minDelayMs?: number) => void;
+    persistWorkspaceSyncPatchSafely: (patch: {
+        phase: 'error';
+        lastErrorMessage: string;
+    }) => void;
+}
+export declare function createSyncAuthCoordinator({ currentWorkspaceId, workspaceSyncPhase, clearWorkspaceRetry, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, reportSyncEvent, setAuthBlocked, setIsAuthenticated, checkAuthSession, ensureCloudWorkspaceReadyForSync, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely }: CreateSyncAuthCoordinatorArgs): {
+    handleSyncAuthFailure: (source: "push" | "pull" | "apply" | "handshake", statusCode: number) => Promise<void>;
+    ensureWorkspaceSyncReady: () => Promise<boolean>;
+};
+export {};