@taskforcehq/taskforce 0.3.302 → 0.3.303

package/dist/core/Taskforce.js

@@ -1175,7 +1175,6 @@ export class TaskforceCore {
             writeGlobalConfig: (config) => this.writeGlobalConfig(config),
         });
         this.planEntitlementService.repairPlanCatalogDefaultsIfNeeded();
-        this.planEntitlementService.repairSignupMonetizationSettingsIfNeeded();
         this.planEntitlementService.normalizeLegacyPlanDataIfNeeded();
         this.planEntitlementService.backfillAccountEntitlements();
         this.repairDetachedAnnotatedAttachmentSessions();
@@ -1209,11 +1208,14 @@ export class TaskforceCore {
     upsertCanonicalEntitlementRecord(input) {
         return this.planEntitlementService.upsertCanonicalEntitlementRecord(input);
     }
+    transitionCanonicalCommercialState(input) {
+        return this.planEntitlementService.transitionCanonicalCommercialState(input);
+    }
     resolveWorkspaceLimitForUser(userId) {
         return this.planEntitlementService.resolveWorkspaceLimitForUser(userId);
     }
-    resolveRegistrationPlanAssignment(selectedPlanVersionIdRaw) {
-        return this.planEntitlementService.resolveRegistrationPlanAssignment(selectedPlanVersionIdRaw);
+    resolveRegistrationOnboardingOutcome(selectedPlanVersionIdRaw) {
+        return this.planEntitlementService.resolveRegistrationOnboardingOutcome(selectedPlanVersionIdRaw);
     }
     createUserBillingRecord(userId, options) {
         return this.planEntitlementService.createUserBillingRecord(userId, options);
@@ -2598,11 +2600,11 @@ export class TaskforceCore {
         const config = this.readConfig(workspaceId, userId) || {};
         return typeof config.jsonBackupEnabled === 'boolean';
     }
-    getSignupMonetizationSettings() {
-        return this.planEntitlementService.getSignupMonetizationSettings();
+    getOnboardingPolicy() {
+        return this.planEntitlementService.getOnboardingPolicy();
     }
-    validateSignupMonetizationSettings(input) {
-        return this.planEntitlementService.validateSignupMonetizationSettings(input);
+    validateOnboardingPolicy(input) {
+        return this.planEntitlementService.validateOnboardingPolicy(input);
     }
     updateGlobalSettings(settings) {
         updateGlobalSettingsService(this.getGlobalSettingsServiceDeps(), settings);
@@ -4375,6 +4377,193 @@ export class TaskforceCore {
         `).run(enabled ? 1 : 0, new Date().toISOString(), this.tenantId, normalizedUserId);
         return Number(result?.changes || 0) > 0;
     }
+    purgeSystemUser(input) {
+        const targetUserId = String(input.targetUserId || '').trim();
+        const actorUserId = String(input.actorUserId || '').trim();
+        const emailConfirmation = String(input.emailConfirmation || '').trim().toLowerCase();
+        if (!targetUserId) {
+            throw new TaskforceRuleError('targetUserId is required', 400, 'TARGET_USER_ID_REQUIRED');
+        }
+        if (!actorUserId || actorUserId === 'anonymous') {
+            throw new TaskforceRuleError('actorUserId is required', 400, 'ACTOR_USER_ID_REQUIRED');
+        }
+        if (!emailConfirmation) {
+            throw new TaskforceRuleError('Email confirmation is required', 400, 'EMAIL_CONFIRMATION_REQUIRED');
+        }
+        if (targetUserId === actorUserId) {
+            throw new TaskforceRuleError('Cannot purge the current system admin session user', 400, 'CURRENT_SYSTEM_USER_PURGE_FORBIDDEN');
+        }
+        return this.db.transaction(() => {
+            const user = this.db.prepare(`
+                SELECT
+                    id,
+                    email,
+                    COALESCE(system_role, 'user') AS system_role,
+                    COALESCE(is_disabled, 0) AS is_disabled
+                FROM users
+                WHERE tenant_id = ? AND id = ?
+                LIMIT 1
+            `).get(this.tenantId, targetUserId);
+            if (!user?.id || !user.email) {
+                throw new TaskforceRuleError('User not found', 404, 'USER_NOT_FOUND');
+            }
+            const normalizedEmail = String(user.email).trim().toLowerCase();
+            if (normalizedEmail !== emailConfirmation) {
+                throw new TaskforceRuleError('Email confirmation did not match the target user', 400, 'EMAIL_CONFIRMATION_MISMATCH');
+            }
+            const currentRole = this.normalizeSystemRole(user.system_role, 'user');
+            const isDisabled = Boolean(user.is_disabled);
+            if (currentRole === 'system_admin' && !isDisabled && this.countSystemAdmins() <= 1) {
+                throw new TaskforceRuleError('Cannot purge the last enabled system admin', 400, 'LAST_SYSTEM_ADMIN_REQUIRED');
+            }
+            const elevatedWorkspaceMemberships = this.db.prepare(`
+                SELECT
+                    m.workspace_id AS workspace_id,
+                    COALESCE(m.role, 'member') AS role,
+                    w.name AS workspace_name
+                FROM workspace_memberships m
+                LEFT JOIN workspaces w
+                  ON w.tenant_id = m.tenant_id
+                 AND w.id = m.workspace_id
+                WHERE m.tenant_id = ?
+                  AND m.user_id = ?
+                  AND COALESCE(m.status, 'active') = 'active'
+                  AND COALESCE(m.role, 'member') IN ('owner', 'admin')
+                ORDER BY COALESCE(w.updated_at, w.created_at) DESC, w.name ASC
+                LIMIT 10
+            `).all(this.tenantId, targetUserId);
+            if (elevatedWorkspaceMemberships.length > 0) {
+                throw new TaskforceRuleError('Cannot purge a user with active owner/admin workspace memberships', 409, 'SYSTEM_USER_PURGE_BLOCKED_ACTIVE_WORKSPACE_ROLE', {
+                    memberships: elevatedWorkspaceMemberships.map((membership) => ({
+                        workspaceId: membership.workspace_id ? String(membership.workspace_id) : null,
+                        workspaceName: membership.workspace_name ? String(membership.workspace_name) : null,
+                        role: membership.role ? String(membership.role) : null
+                    }))
+                });
+            }
+            const billingRow = this.db.prepare(`
+                SELECT
+                    stripe_customer_id,
+                    stripe_subscription_id,
+                    stripe_price_id,
+                    stripe_status,
+                    billing_interval
+                FROM user_billing
+                WHERE tenant_id = ? AND user_id = ?
+                LIMIT 1
+            `).get(this.tenantId, targetUserId);
+            const hasCommercialBillingState = [
+                billingRow?.stripe_customer_id,
+                billingRow?.stripe_subscription_id,
+                billingRow?.stripe_price_id,
+                billingRow?.stripe_status,
+                billingRow?.billing_interval
+            ].some((value) => String(value || '').trim().length > 0);
+            if (hasCommercialBillingState) {
+                throw new TaskforceRuleError('Cannot purge a user with active commercial billing state', 409, 'SYSTEM_USER_PURGE_BLOCKED_BILLING_STATE');
+            }
+            const now = new Date().toISOString();
+            const runCount = (sql, ...params) => Number(this.db.prepare(sql).run(...params)?.changes || 0);
+            const unassignedTaskCount = runCount(`
+                UPDATE tasks
+                SET assignee = 'unassigned',
+                    updated_at = ?
+                WHERE tenant_id = ?
+                  AND assignee = ?
+                  AND is_archived = 0
+            `, now, this.tenantId, targetUserId);
+            const clearedInitiativeOwnerCount = runCount(`
+                UPDATE initiatives
+                SET owner_id = NULL,
+                    updated_at = ?
+                WHERE tenant_id = ?
+                  AND owner_id = ?
+            `, now, this.tenantId, targetUserId);
+            const clearedWorkstreamOwnerCount = runCount(`
+                UPDATE workstreams
+                SET owner_id = NULL,
+                    updated_at = ?
+                WHERE tenant_id = ?
+                  AND owner_id = ?
+            `, now, this.tenantId, targetUserId);
+            const deletedEntitlementCount = runCount(`
+                DELETE FROM account_entitlements
+                WHERE tenant_id = ?
+                  AND account_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedWorkspaceMembershipCount = runCount(`
+                DELETE FROM workspace_memberships
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedAuthTokenCount = runCount(`
+                DELETE FROM auth_tokens
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedAvatarDraftCount = runCount(`
+                DELETE FROM user_avatar_upload_drafts
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedMcpAccessTokenCount = runCount(`
+                DELETE FROM mcp_access_tokens
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedMcpOauthAuthCodeCount = runCount(`
+                DELETE FROM mcp_oauth_auth_codes
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedMcpOauthConnectorGrantCount = runCount(`
+                DELETE FROM mcp_oauth_connector_grants
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedUiStateCount = runCount(`
+                DELETE FROM ui_state
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedUserPreferenceCount = runCount(`
+                DELETE FROM user_preferences
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedUserBillingCount = runCount(`
+                DELETE FROM user_billing
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedUserCount = runCount(`
+                DELETE FROM users
+                WHERE tenant_id = ?
+                  AND id = ?
+            `, this.tenantId, targetUserId);
+            if (deletedUserCount !== 1) {
+                throw new TaskforceRuleError('User not found', 404, 'USER_NOT_FOUND');
+            }
+            return {
+                targetUserId,
+                email: String(user.email),
+                unassignedTaskCount,
+                clearedInitiativeOwnerCount,
+                clearedWorkstreamOwnerCount,
+                deletedWorkspaceMembershipCount,
+                deletedAuthTokenCount,
+                deletedAvatarDraftCount,
+                deletedMcpAccessTokenCount,
+                deletedMcpOauthAuthCodeCount,
+                deletedMcpOauthConnectorGrantCount,
+                deletedUiStateCount,
+                deletedUserPreferenceCount,
+                deletedEntitlementCount,
+                deletedUserBillingCount,
+                deletedUserCount
+            };
+        })();
+    }
     clearActiveAssignmentsForUnavailableActor(actorId, workspaceId, updatedAt) {
         const normalizedActorId = String(actorId || '').trim();
         const normalizedWorkspaceId = String(workspaceId || 'default').trim() || 'default';
@@ -5329,7 +5518,20 @@ export class TaskforceCore {
         const assignFirstSystemAdmin = !this.hasAnySystemAdmin();
         const betaAccess = input.betaAccess !== false;
         const requestedWorkspaceId = String(input.workspaceId || '').trim();
-        const registrationPlanAssignment = this.resolveRegistrationPlanAssignment(input.planVersionId);
+        const onboardingOutcome = this.resolveRegistrationOnboardingOutcome(input.planVersionId);
+        const applyRegistrationCommercialState = (accountId, now) => {
+            this.transitionCanonicalCommercialState({
+                accountId,
+                planVersionId: onboardingOutcome.planVersionId,
+                state: onboardingOutcome.commercialState,
+                effectiveAt: now,
+                billingMirrorPlanId: onboardingOutcome.planId,
+                source: 'registration',
+                updatedBy: 'registration',
+                createdAt: now,
+                updatedAt: now
+            });
+        };
         if (!requestedWorkspaceId || requestedWorkspaceId.toLowerCase() === 'default') {
             const now = new Date().toISOString();
             const userId = this.generateEntityId('user');
@@ -5338,32 +5540,14 @@ export class TaskforceCore {
                 INSERT INTO users (id, tenant_id, email, display_name, auth_provider, external_auth_id, password_hash, system_role, beta_access, is_disabled, created_at, updated_at)
                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?)
             `).run(userId, this.tenantId, email, displayName, 'password', email, hashPassword(password), assignFirstSystemAdmin ? 'system_admin' : 'user', betaAccess ? 1 : 0, now, now);
-            if (registrationPlanAssignment.requiresPlanSelection) {
-                this.createUserBillingRecord(userId, {
-                    entitlementState: 'pending_plan_selection',
-                    planId: null
-                });
-            }
-            if (!registrationPlanAssignment.requiresPlanSelection && registrationPlanAssignment.planVersionId && registrationPlanAssignment.planId) {
-                this.createUserBillingRecord(userId, {
-                    entitlementState: 'active',
-                    planId: registrationPlanAssignment.planId
-                });
-                this.upsertCanonicalEntitlementRecord({
-                    accountId: userId,
-                    planVersionId: registrationPlanAssignment.planVersionId,
-                    state: 'active',
-                    effectiveAt: now,
-                    updatedBy: 'registration',
-                    createdAt: now,
-                    updatedAt: now
-                });
-            }
+            applyRegistrationCommercialState(userId, now);
             return {
                 userId,
                 workspaceId: null,
                 role: 'member',
-                planSelectionRequired: registrationPlanAssignment.requiresPlanSelection
+                planSelectionRequired: onboardingOutcome.requiresPlanSelection,
+                checkoutPending: onboardingOutcome.checkoutPending,
+                commercialState: onboardingOutcome.commercialState
             };
         }
         const workspaceId = requestedWorkspaceId;
@@ -5381,27 +5565,12 @@ export class TaskforceCore {
                 WHERE tenant_id = ? AND id = ?
             `).run(new Date().toISOString(), this.tenantId, created.userId);
         }
-        if (registrationPlanAssignment.requiresPlanSelection) {
-            this.createUserBillingRecord(created.userId, {
-                entitlementState: 'pending_plan_selection',
-                planId: null
-            });
-        }
-        if (!registrationPlanAssignment.requiresPlanSelection && registrationPlanAssignment.planVersionId && registrationPlanAssignment.planId) {
-            this.createUserBillingRecord(created.userId, {
-                entitlementState: 'active',
-                planId: registrationPlanAssignment.planId
-            });
-            this.upsertCanonicalEntitlementRecord({
-                accountId: created.userId,
-                planVersionId: registrationPlanAssignment.planVersionId,
-                state: 'active',
-                updatedBy: 'registration'
-            });
-        }
+        applyRegistrationCommercialState(created.userId);
         return {
             ...created,
-            planSelectionRequired: registrationPlanAssignment.requiresPlanSelection
+            planSelectionRequired: onboardingOutcome.requiresPlanSelection,
+            checkoutPending: onboardingOutcome.checkoutPending,
+            commercialState: onboardingOutcome.commercialState
         };
     }
     createOneTimeAuthToken(userId, purpose, ttlSeconds, workspaceId) {

package/dist/core/Taskforce.mcpAuth.test.js

@@ -27,7 +27,6 @@ function setupWorkspace(core, userId = 'owner-1', workspaceId = 'workspace-1') {
             hasEntitlement: true,
             canAccessApp: true,
             canAccessPlans: true,
-            signupMonetizationStrategy: 'none',
             planSelectionRequired: false,
             message: null,
             entitlement: null
@@ -328,7 +327,6 @@ describe('TaskforceCore MCP auth invalidation', () => {
                     hasEntitlement: false,
                     canAccessApp: false,
                     canAccessPlans: true,
-                    signupMonetizationStrategy: 'none',
                     planSelectionRequired: false,
                     message: 'Suspended for test',
                     entitlement: null

package/dist/core/UserProfileAvatarDrafts.test.js

@@ -13,10 +13,19 @@ function seedPlans(core) {
         versionNumber: 1,
         seatLimit: 1
     });
+    const db = core.db;
+    const now = new Date().toISOString();
+    db.prepare(`
+        INSERT OR IGNORE INTO billing_price_mappings (
+            tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(core.getTenantId(), 'starter-v1', 'month', 'free:starter-v1:month', 'free', 1, 0, null, now, now);
     core.updateGlobalSettings({
-        auth: {
-            signupMonetizationStrategy: 'auto_assign_default',
-            defaultSignupPlanVersionId: 'starter-v1'
+        billing: {
+            onboardingPolicy: {
+                mode: 'auto_grant_free',
+                planVersionId: 'starter-v1'
+            }
         }
     });
 }

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/hooks/useSyncOrchestrator.js

@@ -1571,7 +1571,12 @@ export function useSyncOrchestrator(input) {
                     status: 'error',
                     statusCode: pullResult.status,
                     errorMessage: message,
-                    requestMs: pullResult.pullRequestMs
+                    requestMs: pullResult.pullRequestMs,
+                    details: {
+                        pages: pullResult.pages,
+                        applyMs: pullResult.applyMs,
+                        ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
+                    }
                 });
                 if (pullResult.transient || pullResult.hasTransientApplyFailure || isTransientWorkspaceSyncStatus(pullResult.status)) {
                     scheduleWorkspaceSyncRetry(pullResult.retryAfterMs);
@@ -1638,7 +1643,12 @@ export function useSyncOrchestrator(input) {
                 eventType: workspaceSyncPhase === 'attach-cloud' ? 'bootstrap' : 'pull',
                 status: 'success',
                 changeCount: pullResult.appliedChanges,
-                requestMs: pullResult.pullRequestMs
+                requestMs: pullResult.pullRequestMs,
+                details: {
+                    pages: pullResult.pages,
+                    applyMs: pullResult.applyMs,
+                    ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
+                }
             });
             if (workspaceSyncPhase === 'attach-cloud') {
                 await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
@@ -1727,8 +1737,11 @@ export function useSyncOrchestrator(input) {
         const eventId = String(signal?.eventId || '').trim();
         if (eventId && realtimeSuppressedEventIdsRef.current.delete(eventId))
             return;
-        if (isWorkspaceRetryPending() || workspacePullInFlightRef.current)
+        if (workspacePullInFlightRef.current)
             return;
+        if (isWorkspaceRetryPending()) {
+            clearWorkspaceRetry();
+        }
         if (realtimePullDebounceRef.current !== null) {
             window.clearTimeout(realtimePullDebounceRef.current);
         }
@@ -1742,6 +1755,7 @@ export function useSyncOrchestrator(input) {
         workspaceCloudSyncEnabled,
         workspaceSyncPhase,
         isWorkspaceRetryPending,
+        clearWorkspaceRetry,
         workspacePullInFlightRef,
         pullWorkspaceChangesFromCloud
     ]);

package/dist/hooks/useSyncOrchestrator.retry-closure.test.js

@@ -3,19 +3,44 @@ import { act, renderHook, waitFor } from '@testing-library/react';
 import { useSyncOrchestrator } from './useSyncOrchestrator';
 class MockWebSocket {
     static instances = [];
+    static OPEN = 1;
+    static CLOSED = 3;
     url;
+    readyState = 0;
+    sent = [];
+    listeners = new Map();
     constructor(url) {
         this.url = url;
         MockWebSocket.instances.push(this);
     }
     close() {
-        // noop for orchestration gating tests
+        this.readyState = MockWebSocket.CLOSED;
+        this.emit('close', {});
     }
-    addEventListener() {
-        // noop for orchestration gating tests
+    addEventListener(type, listener) {
+        const bucket = this.listeners.get(type) || new Set();
+        bucket.add(listener);
+        this.listeners.set(type, bucket);
     }
-    send() {
-        // noop for orchestration gating tests
+    send(payload) {
+        if (typeof payload === 'string') {
+            this.sent.push(payload);
+        }
+    }
+    emit(type, event) {
+        const bucket = this.listeners.get(type);
+        if (!bucket)
+            return;
+        for (const listener of bucket) {
+            listener(event);
+        }
+    }
+    open() {
+        this.readyState = MockWebSocket.OPEN;
+        this.emit('open', {});
+    }
+    message(payload) {
+        this.emit('message', { data: JSON.stringify(payload) });
     }
 }
 const { ensureCloudWorkspaceReadyForSyncServiceMock, runWorkspacePullSyncServiceMock, runWorkspacePushSyncServiceMock, syncUserGlobalSettingsServiceMock } = vi.hoisted(() => ({
@@ -206,6 +231,73 @@ describe('useSyncOrchestrator', () => {
         expect(MockWebSocket.instances[0]?.url).toBe('wss://api.example.com/taskforce-ws');
         unmount();
     });
+    it('lets a realtime signal break transient retry backoff and pull immediately', async () => {
+        vi.useFakeTimers();
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        runWorkspacePullSyncServiceMock
+            .mockResolvedValueOnce({
+            success: false,
+            kind: 'pull_http',
+            status: 502,
+            transient: true,
+            retryAfterMs: 60_000,
+            cursor: null,
+            pages: 0,
+            appliedChanges: 0,
+            pullRequestMs: 1,
+            applyMs: 0,
+            pulledDeleteTaskIds: new Set(),
+            pulledActiveUpserts: false,
+            pulledArchivedUpserts: false,
+            documentDecryptFailures: []
+        })
+            .mockResolvedValueOnce({
+            success: true,
+            syncedAt: '2026-03-15T18:05:00.000Z',
+            cursor: null,
+            pages: 1,
+            appliedChanges: 1,
+            pullRequestMs: 1,
+            applyMs: 0,
+            pulledDeleteTaskIds: new Set(),
+            pulledActiveUpserts: true,
+            pulledArchivedUpserts: false,
+            documentDecryptFailures: []
+        });
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput({ realtimeSyncEnabled: true })
+        });
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'active',
+                pullCursor: null
+            });
+        });
+        await act(async () => {
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(result.current.workspaceRetryAt).not.toBeNull();
+        expect(MockWebSocket.instances).toHaveLength(1);
+        expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledTimes(1);
+        act(() => {
+            MockWebSocket.instances[0]?.open();
+            MockWebSocket.instances[0]?.message({
+                type: 'taskforce:update',
+                workspaceId: 'workspace-local-active'
+            });
+        });
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(300);
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledTimes(2);
+        expect(result.current.workspaceRetryAt).toBeNull();
+        expect(result.current.workspaceLastPullAt).toBe('2026-03-15T18:05:00.000Z');
+        unmount();
+    });
     it('retries transient push failures automatically', async () => {
         runWorkspacePushSyncServiceMock
             .mockResolvedValueOnce({

package/dist/hooks/useTaskforce.d.ts

@@ -249,6 +249,9 @@ export declare function useTaskforce({ config, initialTaskId, onTaskCountChange,
         emailSent?: boolean;
         emailError?: string;
         workspaceSetupRequired?: boolean;
+        planSelectionRequired?: boolean;
+        checkoutPending?: boolean;
+        commercialState?: string | null;
     }>;
     updateCurrentUserProfile: (input: {
         displayName: string;

package/dist/hooks/useTaskforce.js

@@ -229,6 +229,8 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
         if (!path.startsWith('/'))
             return path;
         const isCloudScopedPath = path.startsWith('/api/taskforce/auth/')
+            || path.startsWith('/api/taskforce/account/')
+            || path.startsWith('/api/taskforce/billing/')
             || path.startsWith('/api/taskforce/sync/')
             || path.startsWith('/api/taskforce/settings/mcp/');
         if (!isCloudHost && isCloudScopedPath && (!runtimeConfigReady || runtimeConfigOverride.cloudAuthViaLocalProxy)) {
@@ -1999,7 +2001,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
     const retryBootstrapChecks = useCallback(async () => {
         setBootstrapError(null);
         markBootstrapPhase('auth');
-        const authenticated = await checkAuthSession();
+        const authenticated = await checkAuthSession({ force: true });
         if (workspaceSwitchingEnabled && authenticated) {
             const workspaceResolution = await resolveWorkspaceAfterAuth();
             if (!workspaceResolution.success || workspaceResolution.workspaceSetupRequired) {
@@ -2066,7 +2068,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             if (!res.ok || data?.success === false) {
                 return { success: false, error: data?.error || `Failed to delete workspace (${res.status})`, code: data?.code };
             }
-            await checkAuthSession();
+            await checkAuthSession({ force: true });
             await Promise.all([fetchConfig(), fetchWorkspaces()]);
             const nextWorkspaceId = typeof data?.nextWorkspaceId === 'string' ? data.nextWorkspaceId.trim() : '';
             if (nextWorkspaceId) {
@@ -2168,7 +2170,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 return { success: false, error: data?.error || 'Sign in failed.', code: data?.code };
             }
             setError('');
-            await checkAuthSession();
+            await checkAuthSession({ force: true });
             const workspaceResolution = await resolveWorkspaceAfterAuth();
             if (!workspaceResolution.success) {
                 return {
@@ -2229,6 +2231,9 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
             return {
                 success: true,
                 workspaceSetupRequired: Boolean(data?.workspaceSetupRequired),
+                planSelectionRequired: data?.planSelectionRequired === true,
+                checkoutPending: data?.checkoutPending === true,
+                commercialState: typeof data?.commercialState === 'string' ? data.commercialState : null,
                 verificationRequired: Boolean(data?.verificationRequired),
                 verificationToken: typeof data?.verificationToken === 'string' ? data.verificationToken : undefined,
                 emailSent: data?.emailSent !== false,
@@ -2443,7 +2448,7 @@ export function useTaskforce({ config = {}, initialTaskId, onTaskCountChange, on
                 return { success: false, error: data?.error || 'Invite acceptance failed.', code: data?.code };
             }
             setError('');
-            await checkAuthSession();
+            await checkAuthSession({ force: true });
             const preferredWorkspaceId = typeof data?.workspaceId === 'string' ? data.workspaceId : null;
             const workspaceResolution = await resolveWorkspaceAfterAuth({ preferredWorkspaceId });
             if (!workspaceResolution.success) {