@taskforcehq/taskforce 0.3.302 → 0.3.304

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/core/types.d.ts

@@ -268,8 +268,9 @@ export interface GlobalTaskforceSettings {
         authRateLimitEnabled?: boolean;
         authRateLimitMaxRequests?: number;
         authRateLimitWindowMs?: number;
-        signupMonetizationStrategy?: 'auto_assign_default' | 'plan_selection_required';
-        defaultSignupPlanVersionId?: string | null;
+    };
+    billing?: {
+        onboardingPolicy?: OnboardingPolicy;
     };
     site?: {
         showRunTaskforceLocally?: boolean;
@@ -299,14 +300,14 @@ export interface UserGlobalSyncSettings {
         weekStartsOn?: 'sunday' | 'monday';
     };
 }
-export type SignupMonetizationStrategy = 'auto_assign_default' | 'plan_selection_required';
-export interface SignupMonetizationSettings {
-    strategy: SignupMonetizationStrategy;
-    defaultSignupPlanVersionId: string | null;
+export type OnboardingPolicyMode = 'require_plan_selection' | 'auto_grant_free' | 'auto_start_trial';
+export interface OnboardingPolicy {
+    mode: OnboardingPolicyMode;
+    planVersionId: string | null;
 }
-export interface SignupMonetizationValidationResult {
+export interface OnboardingPolicyValidationResult {
     valid: boolean;
-    code?: 'SIGNUP_PLAN_VERSION_REQUIRED' | 'SIGNUP_PLAN_VERSION_NOT_FOUND' | 'SIGNUP_PLAN_NOT_ENABLED';
+    code?: 'ONBOARDING_PLAN_VERSION_REQUIRED' | 'ONBOARDING_PLAN_VERSION_NOT_FOUND' | 'ONBOARDING_PLAN_NOT_ENABLED' | 'ONBOARDING_PLAN_MUST_BE_FREE' | 'ONBOARDING_PLAN_TRIAL_REQUIRED';
     message?: string;
     details?: Record<string, unknown>;
 }
@@ -441,7 +442,7 @@ export interface McpAuditLogRecord {
     reasonCode: string | null;
     details: Record<string, unknown>;
 }
-export type EntitlementState = 'active' | 'trialing' | 'grace' | 'suspended' | 'canceled';
+export type EntitlementState = 'pending_plan_selection' | 'checkout_pending' | 'active' | 'trialing' | 'grace' | 'suspended' | 'canceled';
 export type PlanFeatureAccess = 'enabled' | 'disabled' | 'limited';
 export interface PlanFeatureSnapshot {
     featureKey: string;
@@ -499,17 +500,15 @@ export interface AccountAccessStatus_Ok {
     hasEntitlement: true;
     canAccessApp: true;
     canAccessPlans: true;
-    signupMonetizationStrategy: SignupMonetizationStrategy;
     planSelectionRequired: false;
     message: null;
     entitlement: AccountEntitlementSnapshot;
 }
 export interface AccountAccessStatus_Blocked {
-    gate: 'plan_selection_required' | 'misconfigured' | 'missing_entitlement';
+    gate: 'plan_selection_required' | 'checkout_pending' | 'misconfigured' | 'missing_entitlement';
     hasEntitlement: boolean;
     canAccessApp: false;
     canAccessPlans: true;
-    signupMonetizationStrategy: SignupMonetizationStrategy;
     planSelectionRequired: boolean;
     message: string;
     entitlement: AccountEntitlementSnapshot | null;

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 {};

package/dist/hooks/sync/auth.js

@@ -0,0 +1,61 @@
+import { isTransientWorkspaceSyncStatus } from '../../sync/syncService';
+import { isValidWorkspaceKey } from './orchestratorShared';
+export function createSyncAuthCoordinator({ currentWorkspaceId, workspaceSyncPhase, clearWorkspaceRetry, setWorkspaceSyncBusy, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, reportSyncEvent, setAuthBlocked, setIsAuthenticated, checkAuthSession, ensureCloudWorkspaceReadyForSync, scheduleWorkspaceSyncRetry, persistWorkspaceSyncPatchSafely }) {
+    const handleSyncAuthFailure = async (source, statusCode) => {
+        clearWorkspaceRetry();
+        setWorkspaceSyncBusy(false);
+        setUserGlobalSyncStatus('error');
+        const message = 'Session expired. Sign in again to resume cloud sync.';
+        setUserGlobalSyncError(message);
+        setWorkspaceLastErrorMessage(message);
+        setWorkspaceLastErrorAt(new Date().toISOString());
+        reportSyncEvent(currentWorkspaceId, {
+            eventType: source === 'handshake' ? 'handshake' : source,
+            status: 'error',
+            statusCode,
+            errorMessage: message
+        });
+        setAuthBlocked(true);
+        setIsAuthenticated(false);
+        await checkAuthSession();
+    };
+    const ensureWorkspaceSyncReady = async () => {
+        if (!isValidWorkspaceKey(currentWorkspaceId)) {
+            const message = 'Workspace sync blocked: local workspace ID is unresolved.';
+            setWorkspaceLastErrorMessage(message);
+            setWorkspaceLastErrorAt(new Date().toISOString());
+            setUserGlobalSyncError(message);
+            setUserGlobalSyncStatus('error');
+            return false;
+        }
+        const ensured = await ensureCloudWorkspaceReadyForSync();
+        if (ensured.success)
+            return true;
+        if (ensured.statusCode === 401) {
+            await handleSyncAuthFailure('handshake', 401);
+            return false;
+        }
+        const message = ensured.error || 'Workspace sync handshake failed.';
+        setWorkspaceLastErrorMessage(message);
+        setWorkspaceLastErrorAt(new Date().toISOString());
+        setUserGlobalSyncError(message);
+        setUserGlobalSyncStatus('error');
+        reportSyncEvent(currentWorkspaceId, {
+            eventType: 'handshake',
+            status: 'error',
+            statusCode: ensured.statusCode,
+            errorMessage: message
+        });
+        if (ensured.transient || isTransientWorkspaceSyncStatus(ensured.statusCode)) {
+            scheduleWorkspaceSyncRetry(ensured.retryAfterMs);
+        }
+        else if (workspaceSyncPhase === 'active') {
+            persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+        }
+        return false;
+    };
+    return {
+        handleSyncAuthFailure,
+        ensureWorkspaceSyncReady
+    };
+}

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

@@ -0,0 +1,34 @@
+import type { MutableRefObject } from 'react';
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+interface BootstrapPhaseTrackingArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    lastBootstrapPhaseRef: MutableRefObject<WorkspaceSyncPhase>;
+    bootstrapPhaseStartedAtRef: MutableRefObject<number | null>;
+    bootstrapLastProgressAtRef: MutableRefObject<number | null>;
+}
+export declare function syncBootstrapPhaseTracking({ workspaceSyncPhase, lastBootstrapPhaseRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef }: BootstrapPhaseTrackingArgs): void;
+interface BootstrapTimeoutMonitorArgs {
+    currentWorkspaceId: string;
+    workspaceCloudSyncEnabled: boolean;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    workspacePullInFlightRef: MutableRefObject<boolean>;
+    workspacePushInFlightRef: MutableRefObject<boolean>;
+    bootstrapPhaseStartedAtRef: MutableRefObject<number | null>;
+    bootstrapLastProgressAtRef: MutableRefObject<number | null>;
+    setWorkspaceLastErrorMessage: (value: string) => void;
+    setWorkspaceLastErrorAt: (value: string) => void;
+    setUserGlobalSyncStatus: (value: 'error') => void;
+    setUserGlobalSyncError: (value: string) => void;
+    setWorkspaceSyncBusy: (value: boolean) => void;
+    persistWorkspaceSyncPatchSafely: (patch: {
+        phase: 'error';
+        lastErrorMessage: string;
+    }) => void;
+}
+export declare function createBootstrapTimeoutMonitor({ currentWorkspaceId, workspaceCloudSyncEnabled, workspaceSyncPhase, workspacePullInFlightRef, workspacePushInFlightRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceSyncBusy, persistWorkspaceSyncPatchSafely }: BootstrapTimeoutMonitorArgs): (() => void) | undefined;
+export declare function resolveRepairPhase(args: {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    lastBootstrapPhase: WorkspaceSyncPhase;
+    workspaceLastPullAt: string | null;
+}): WorkspaceSyncPhase;
+export {};

package/dist/hooks/sync/bootstrap.js

@@ -0,0 +1,52 @@
+import { WORKSPACE_BOOTSTRAP_TIMEOUT_MS, logSyncDebug } from './orchestratorShared';
+export function syncBootstrapPhaseTracking({ workspaceSyncPhase, lastBootstrapPhaseRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef }) {
+    if (workspaceSyncPhase === 'attach-cloud' || workspaceSyncPhase === 'provision-local') {
+        lastBootstrapPhaseRef.current = workspaceSyncPhase;
+        if (bootstrapPhaseStartedAtRef.current === null) {
+            bootstrapPhaseStartedAtRef.current = Date.now();
+        }
+        bootstrapLastProgressAtRef.current = null;
+        return;
+    }
+    bootstrapPhaseStartedAtRef.current = null;
+    bootstrapLastProgressAtRef.current = null;
+}
+export function createBootstrapTimeoutMonitor({ currentWorkspaceId, workspaceCloudSyncEnabled, workspaceSyncPhase, workspacePullInFlightRef, workspacePushInFlightRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, setWorkspaceLastErrorMessage, setWorkspaceLastErrorAt, setUserGlobalSyncStatus, setUserGlobalSyncError, setWorkspaceSyncBusy, persistWorkspaceSyncPatchSafely }) {
+    if (!workspaceCloudSyncEnabled)
+        return undefined;
+    if (workspaceSyncPhase !== 'attach-cloud' && workspaceSyncPhase !== 'provision-local')
+        return undefined;
+    const intervalId = window.setInterval(() => {
+        if (workspaceSyncPhase !== 'attach-cloud' && workspaceSyncPhase !== 'provision-local')
+            return;
+        if (workspacePullInFlightRef.current || workspacePushInFlightRef.current)
+            return;
+        const lastActivity = Math.max(bootstrapPhaseStartedAtRef.current ?? 0, bootstrapLastProgressAtRef.current ?? 0);
+        if (lastActivity > 0 && (Date.now() - lastActivity) < WORKSPACE_BOOTSTRAP_TIMEOUT_MS)
+            return;
+        const phaseLabel = workspaceSyncPhase === 'attach-cloud' ? 'initial cloud pull' : 'initial cloud upload';
+        const message = `Workspace sync ${phaseLabel} stalled. Press Repair to restart sync for this workspace.`;
+        setWorkspaceLastErrorMessage(message);
+        setWorkspaceLastErrorAt(new Date().toISOString());
+        setUserGlobalSyncStatus('error');
+        setUserGlobalSyncError(message);
+        setWorkspaceSyncBusy(false);
+        persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
+        logSyncDebug('workspace_sync_bootstrap_timeout', {
+            workspaceId: currentWorkspaceId,
+            phase: workspaceSyncPhase
+        });
+    }, 10_000);
+    return () => window.clearInterval(intervalId);
+}
+export function resolveRepairPhase(args) {
+    const { workspaceSyncPhase, lastBootstrapPhase, workspaceLastPullAt } = args;
+    if (workspaceSyncPhase === 'provision-local')
+        return 'provision-local';
+    if (workspaceSyncPhase === 'attach-cloud')
+        return 'attach-cloud';
+    if (lastBootstrapPhase === 'provision-local' || lastBootstrapPhase === 'attach-cloud') {
+        return lastBootstrapPhase;
+    }
+    return workspaceLastPullAt ? 'attach-cloud' : 'provision-local';
+}

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

@@ -0,0 +1,36 @@
+import type { WorkspaceTaxonomyState } from '../../shared/taxonomyState.js';
+import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncTaskEventSnapshot } from '../../sync/workspaceSyncModel';
+import type { TaskItem } from '../../types';
+export declare const USER_GLOBAL_SYNC_META_KEY = "taskforce.userGlobalSyncMeta.v1";
+export declare const SYNC_DEBUG_LOG_KEY = "taskforce.syncDebug.v1";
+export declare const WORKSPACE_BOOTSTRAP_TIMEOUT_MS = 120000;
+export declare const WORKSPACE_SYNC_WATERMARKS_KEY_PREFIX = "taskforce.syncWatermarks.v3";
+export declare const WORKSPACE_FULL_RECONCILE_INTERVAL_MS: number;
+export declare const WORKSPACE_CONCURRENT_WINDOW_MESSAGE = "Another local window is already syncing this workspace. Wait a few seconds, or press Repair in that window.";
+export declare function isValidWorkspaceKey(workspaceId: string): boolean;
+export declare function logSyncDebug(event: string, details?: Record<string, unknown>): void;
+export declare function normalizeWorkspaceSyncAiProfileSnapshotEntry(entry: any): WorkspaceSyncAiProfileSnapshot;
+export declare function readUserGlobalSyncMeta(): Record<string, {
+    updatedAt: string;
+}>;
+export declare function writeUserGlobalSyncMeta(next: Record<string, {
+    updatedAt: string;
+}>): void;
+export declare function buildTaxonomyStateFingerprint(taxonomyState?: WorkspaceTaxonomyState): string;
+export declare function flattenDocumentReviewComments(sessions: WorkspaceSyncDocumentReviewSessionSnapshot[]): WorkspaceSyncDocumentReviewCommentSnapshot[];
+export declare function flattenTaskEvents(tasks: TaskItem[], archivedTasks: TaskItem[]): WorkspaceSyncTaskEventSnapshot[];
+export interface PersistedSyncWatermarks {
+    taskWatermarks: Map<string, string>;
+    initiativeWatermarks: Map<string, string>;
+    workstreamWatermarks: Map<string, string>;
+    documentWatermarks: Map<string, string>;
+    assetWatermarks: Map<string, string>;
+    documentReviewSessionWatermarks: Map<string, string>;
+    documentReviewCommentWatermarks: Map<string, string>;
+    annotatedAttachmentSessionWatermarks: Map<string, string>;
+    taskEventWatermarks: Map<string, string>;
+}
+export declare function readPersistedSyncWatermarks(workspaceId: string, taxonomyStateFingerprint?: string): PersistedSyncWatermarks | null;
+export declare function savePersistedSyncWatermarks(workspaceId: string, data: PersistedSyncWatermarks & {
+    taxonomyStateFingerprint?: string;
+}): void;