@taskforcehq/taskforce 0.3.305 → 0.3.307

package/dist/core/types.d.ts

@@ -275,6 +275,10 @@ export interface GlobalTaskforceSettings {
     site?: {
         showRunTaskforceLocally?: boolean;
         pricingPageEnabled?: boolean;
+        animatedBackgroundEnabled?: boolean;
+        siteTheme?: 'dark' | 'light';
+        pricingPageTitle?: string;
+        pricingPageDescription?: string;
     };
     setup?: {
         mode?: 'core' | 'operations';
@@ -287,6 +291,25 @@ export interface GlobalTaskforceSettings {
         signedUploadTtlSeconds?: number;
         signedDownloadTtlSeconds?: number;
     };
+    oauthProviders?: {
+        google?: {
+            enabled?: boolean;
+            clientId?: string;
+            clientSecret?: string;
+        };
+        github?: {
+            enabled?: boolean;
+            clientId?: string;
+            clientSecret?: string;
+        };
+        apple?: {
+            enabled?: boolean;
+            servicesId?: string;
+            teamId?: string;
+            keyId?: string;
+            privateKeyPem?: string;
+        };
+    };
 }
 export interface SettingsSplitPayload {
     system: GlobalTaskforceSettings;
@@ -303,11 +326,11 @@ export interface UserGlobalSyncSettings {
 export type OnboardingPolicyMode = 'require_plan_selection' | 'auto_grant_free' | 'auto_start_trial';
 export interface OnboardingPolicy {
     mode: OnboardingPolicyMode;
-    planVersionId: string | null;
+    planId: string | null;
 }
 export interface OnboardingPolicyValidationResult {
     valid: boolean;
-    code?: 'ONBOARDING_PLAN_VERSION_REQUIRED' | 'ONBOARDING_PLAN_VERSION_NOT_FOUND' | 'ONBOARDING_PLAN_NOT_ENABLED' | 'ONBOARDING_PLAN_MUST_BE_FREE' | 'ONBOARDING_PLAN_TRIAL_REQUIRED';
+    code?: 'ONBOARDING_PLAN_REQUIRED' | 'ONBOARDING_PLAN_NOT_FOUND' | 'ONBOARDING_PLAN_NOT_ENABLED' | 'ONBOARDING_PLAN_MUST_BE_FREE' | 'ONBOARDING_PLAN_TRIAL_REQUIRED';
     message?: string;
     details?: Record<string, unknown>;
 }
@@ -316,6 +339,36 @@ export type SystemRole = 'system_admin' | 'user';
 export type PermissionMode = 'read-only' | 'read-write';
 export type AuthTokenPurpose = 'email_verification' | 'password_reset' | 'invite_accept';
 export type McpAccessTokenScope = 'tasks:read' | 'tasks:write' | 'workspace:read';
+export type UserAuthProvider = 'password' | 'google' | 'github' | 'apple';
+export interface UserAuthIdentity {
+    id: string;
+    tenantId: string;
+    userId: string;
+    provider: UserAuthProvider;
+    providerSubject: string | null;
+    providerEmail: string | null;
+    providerEmailVerified: boolean | null;
+    displayNameSnapshot: string | null;
+    avatarUrlSnapshot: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastLoginAt: string | null;
+    linkedAt: string | null;
+    disabledAt: string | null;
+}
+export type InviteeState = 'pending_setup' | 'existing_account';
+export interface InviteAcceptanceDetails {
+    state: 'valid' | 'expired' | 'used' | 'missing' | 'revoked';
+    email?: string;
+    userId?: string;
+    workspaceId?: string;
+    inviteeState?: InviteeState;
+    availableMethods?: UserAuthProvider[];
+    /** @deprecated use inviteeState */
+    inviteeKind?: 'existing_user' | 'new_user';
+    /** @deprecated use availableMethods */
+    passwordRequired?: boolean;
+}
 export type McpAccessTokenStatus = 'active' | 'revoked' | 'expired';
 export type McpOAuthProvider = 'chatgpt' | 'claude';
 export type McpOAuthClientStatus = 'active' | 'revoked';
@@ -326,6 +379,8 @@ export interface UserAccessRecord {
     role: AccessRole;
     permissionMode: PermissionMode;
     disabled: boolean;
+    accountDisabled?: boolean;
+    workspaceDisabled?: boolean;
     betaAccess: boolean;
 }
 export interface UserIdentityRecord {
@@ -340,6 +395,7 @@ export interface WorkspaceUserRecord {
     userId: string;
     email: string;
     displayName?: string | null;
+    avatarUrl?: string | null;
     role: AccessRole;
     permissionMode: PermissionMode;
     betaAccess: boolean;
@@ -453,6 +509,9 @@ export interface PlanFeatureCatalogItem {
     featureKey: string;
     label: string;
     description: string;
+    publicLabel?: string | null;
+    publicDescription?: string | null;
+    publicDisplayOrder?: number | null;
     allowedAccessModes: PlanFeatureAccess[];
     configTemplate: Record<string, unknown>;
     dependsOn?: string[];
@@ -470,10 +529,20 @@ export interface PlanVersionSnapshot {
 export interface PlanCatalogSnapshot {
     planId: string;
     displayName: string;
+    description: string | null;
     status: 'active' | 'archived';
     createdAt: string;
     updatedAt: string;
 }
+export interface OnboardingPlanOption {
+    planId: string;
+    planDisplayName: string;
+    defaultPlanVersionId: string;
+    defaultVersionNumber: number;
+    planStatus: 'active' | 'archived';
+    supportsAutoGrantFree: boolean;
+    supportsAutoStartTrial: boolean;
+}
 export interface AccountEntitlementSnapshot {
     accountId: string;
     planVersionId: string;
@@ -520,6 +589,7 @@ export interface PasswordAuthResult {
         userId: string;
         workspaceId: string;
         role: AccessRole;
+        identityId?: string;
     };
     code?: 'INVALID_CREDENTIALS' | 'EMAIL_NOT_VERIFIED';
 }
@@ -612,4 +682,7 @@ export interface McpOAuthAccessTokenAuthResult {
     provider: McpOAuthProvider;
     scopes: McpAccessTokenScope[];
     status: McpOAuthGrantStatus;
+    aiProfileId?: string | null;
+    aiProfileToken?: string | null;
+    aiProfileName?: string | null;
 }

package/dist/hooks/auth/useTaskforceAuthBootstrap.js

@@ -1,6 +1,11 @@
 import { useCallback, useEffect } from 'react';
 import { createDefaultAssigneeOptions } from '../../utils/assignees';
+import { logBootstrapDebug } from '../workspace/workspaceLocalState';
 import { persistLocalMutationActorUserId, readLocalMutationActorUserId } from '../../utils/taskforceApiClient';
+import { AUTH_SESSION_REQUEST_TIMEOUT_MS } from '../bootstrapTimeouts';
+function getBootstrapTimestamp() {
+    return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
 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;
@@ -41,11 +46,20 @@ export function useTaskforceAuthBootstrap({ runtimeConfigReady, shouldProbeCloud
         const requestEpoch = ++authSessionEpochRef.current;
         let request = null;
         request = (async () => {
+            const startedAt = getBootstrapTimestamp();
             const abortController = new AbortController();
             const timeoutId = typeof window !== 'undefined'
-                ? window.setTimeout(() => abortController.abort(), 8000)
+                ? window.setTimeout(() => abortController.abort(), AUTH_SESSION_REQUEST_TIMEOUT_MS)
                 : null;
             const isStaleRequest = () => authSessionEpochRef.current !== requestEpoch;
+            const logResult = (event, details) => {
+                logBootstrapDebug(event, {
+                    durationMs: Math.max(0, Math.round(getBootstrapTimestamp() - startedAt)),
+                    force,
+                    sessionUrl,
+                    ...details
+                });
+            };
             try {
                 const res = await fetch(sessionUrl, {
                     method: 'GET',
@@ -59,6 +73,7 @@ export function useTaskforceAuthBootstrap({ runtimeConfigReady, shouldProbeCloud
                 if (res.status === 429) {
                     setAuthSessionResolved(true);
                     setAuthStateReadyRefs(authSessionLastResultRef.current, true, false);
+                    logResult('auth_session_rate_limited', { status: res.status });
                     return authSessionLastResultRef.current;
                 }
                 if (!res.ok) {
@@ -70,6 +85,7 @@ export function useTaskforceAuthBootstrap({ runtimeConfigReady, shouldProbeCloud
                     setAuthSessionResolved(true);
                     setAuthStateReadyRefs(false, true, false);
                     authSessionLastResultRef.current = false;
+                    logResult('auth_session_request_failed', { status: res.status });
                     return false;
                 }
                 const data = await res.json();
@@ -117,9 +133,16 @@ export function useTaskforceAuthBootstrap({ runtimeConfigReady, shouldProbeCloud
                 authSessionLastResultRef.current = authenticated;
                 if (authenticated)
                     markBootstrapPhase('ready');
+                logResult('auth_session_resolved', {
+                    status: res.status,
+                    authenticated,
+                    workspaceId: authenticated ? workspaceId : '',
+                    userId: authenticated ? userId : 'anonymous',
+                    authRequiredForApi: nextAuthRequiredForApi
+                });
                 return authenticated;
             }
-            catch {
+            catch (error) {
                 if (isStaleRequest()) {
                     return authSessionLastResultRef.current;
                 }
@@ -129,6 +152,9 @@ export function useTaskforceAuthBootstrap({ runtimeConfigReady, shouldProbeCloud
                 setAuthStateReadyRefs(false, true, false);
                 authSessionLastResultRef.current = false;
                 markBootstrapStalled('Unable to verify your session.');
+                logResult('auth_session_exception', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
                 return authSessionLastResultRef.current;
             }
             finally {

package/dist/hooks/bootstrapTimeouts.d.ts

@@ -0,0 +1,4 @@
+export declare const BOOTSTRAP_REQUEST_TIMEOUT_MS = 12000;
+export declare const CLOUD_BOOTSTRAP_REQUEST_TIMEOUT_MS = 30000;
+export declare const AUTH_SESSION_REQUEST_TIMEOUT_MS = 20000;
+export declare function resolveBootstrapRequestTimeoutMs(runtimeMode: 'local' | 'cloud'): number;

package/dist/hooks/bootstrapTimeouts.js

@@ -0,0 +1,8 @@
+export const BOOTSTRAP_REQUEST_TIMEOUT_MS = 12_000;
+export const CLOUD_BOOTSTRAP_REQUEST_TIMEOUT_MS = 30_000;
+export const AUTH_SESSION_REQUEST_TIMEOUT_MS = 20_000;
+export function resolveBootstrapRequestTimeoutMs(runtimeMode) {
+    return runtimeMode === 'cloud'
+        ? CLOUD_BOOTSTRAP_REQUEST_TIMEOUT_MS
+        : BOOTSTRAP_REQUEST_TIMEOUT_MS;
+}

package/dist/hooks/bootstrapTimeouts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/bootstrapTimeouts.test.js

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { AUTH_SESSION_REQUEST_TIMEOUT_MS, BOOTSTRAP_REQUEST_TIMEOUT_MS, CLOUD_BOOTSTRAP_REQUEST_TIMEOUT_MS, resolveBootstrapRequestTimeoutMs } from './bootstrapTimeouts';
+describe('bootstrap timeout budgets', () => {
+    it('keeps local bootstrap checks short', () => {
+        expect(resolveBootstrapRequestTimeoutMs('local')).toBe(BOOTSTRAP_REQUEST_TIMEOUT_MS);
+    });
+    it('gives cloud bootstrap checks enough room for edge delays', () => {
+        expect(resolveBootstrapRequestTimeoutMs('cloud')).toBe(CLOUD_BOOTSTRAP_REQUEST_TIMEOUT_MS);
+        expect(CLOUD_BOOTSTRAP_REQUEST_TIMEOUT_MS).toBeGreaterThan(BOOTSTRAP_REQUEST_TIMEOUT_MS);
+        expect(AUTH_SESSION_REQUEST_TIMEOUT_MS).toBeGreaterThan(BOOTSTRAP_REQUEST_TIMEOUT_MS);
+    });
+});

package/dist/hooks/sync/bootstrap.js

@@ -45,6 +45,8 @@ export function resolveRepairPhase(args) {
         return 'provision-local';
     if (workspaceSyncPhase === 'attach-cloud')
         return 'attach-cloud';
+    if (workspaceSyncPhase === 'active' || lastBootstrapPhase === 'active')
+        return 'active';
     if (lastBootstrapPhase === 'provision-local' || lastBootstrapPhase === 'attach-cloud') {
         return lastBootstrapPhase;
     }

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

@@ -0,0 +1,37 @@
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+export type WorkspaceSyncBlockedReason = 'cloud-auth-unconfigured' | 'runtime-not-local' | 'sync-disabled' | 'invalid-workspace' | 'repair-active' | 'attach-cloud' | 'provision-local' | 'auth-required' | 'push-in-flight' | 'pull-in-flight' | 'retry-pending' | 'lease-held';
+export type WorkspaceSyncOperation = 'pull' | 'push' | 'repair';
+export type WorkspaceSyncControlPlaneDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: WorkspaceSyncBlockedReason;
+    retainPendingSignature: boolean;
+};
+interface WorkspaceSyncControlPlaneBaseArgs {
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    workspaceCloudSyncEnabled: boolean;
+    currentWorkspaceId: string;
+    isAuthenticated: boolean;
+}
+interface PushSyncReadinessArgs extends WorkspaceSyncControlPlaneBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    repairModeActive: boolean;
+    repairModeBypass: boolean;
+    pushInFlight: boolean;
+    pullInFlight: boolean;
+}
+interface PullSyncReadinessArgs extends WorkspaceSyncControlPlaneBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    repairModeActive: boolean;
+    repairModeBypass: boolean;
+    retryPending: boolean;
+    pushInFlight: boolean;
+    pullInFlight: boolean;
+}
+export declare function resolvePushSyncReadiness(args: PushSyncReadinessArgs): WorkspaceSyncControlPlaneDecision;
+export declare function resolvePullSyncReadiness(args: PullSyncReadinessArgs): WorkspaceSyncControlPlaneDecision;
+export declare function resolveRetrySyncReadiness(args: WorkspaceSyncControlPlaneBaseArgs): WorkspaceSyncControlPlaneDecision;
+export declare function createWorkspaceSyncLeaseHeldDecision(operation: WorkspaceSyncOperation): WorkspaceSyncControlPlaneDecision;
+export {};

package/dist/hooks/sync/controlPlane.js

@@ -0,0 +1,78 @@
+import { isValidWorkspaceKey } from './orchestratorShared';
+const ALLOW_SYNC_OPERATION = { allowed: true };
+function blockSyncOperation(reason, options) {
+    return {
+        allowed: false,
+        reason,
+        retainPendingSignature: options?.retainPendingSignature === true
+    };
+}
+function resolveBaseSyncReadiness(args, options) {
+    if (!args.cloudAuthConfigured)
+        return blockSyncOperation('cloud-auth-unconfigured');
+    if (args.runtimeMode !== 'local')
+        return blockSyncOperation('runtime-not-local');
+    if (!args.workspaceCloudSyncEnabled)
+        return blockSyncOperation('sync-disabled');
+    if ((options?.requireValidWorkspace ?? true) && !isValidWorkspaceKey(args.currentWorkspaceId)) {
+        return blockSyncOperation('invalid-workspace');
+    }
+    return null;
+}
+export function resolvePushSyncReadiness(args) {
+    const baseReadiness = resolveBaseSyncReadiness(args);
+    if (baseReadiness)
+        return baseReadiness;
+    if (args.repairModeActive && !args.repairModeBypass) {
+        return blockSyncOperation('repair-active', { retainPendingSignature: true });
+    }
+    if (args.workspaceSyncPhase === 'attach-cloud') {
+        return blockSyncOperation('attach-cloud', { retainPendingSignature: true });
+    }
+    if (!args.isAuthenticated) {
+        return blockSyncOperation('auth-required');
+    }
+    if (args.pushInFlight) {
+        return blockSyncOperation('push-in-flight', { retainPendingSignature: true });
+    }
+    if (args.pullInFlight) {
+        return blockSyncOperation('pull-in-flight', { retainPendingSignature: true });
+    }
+    return ALLOW_SYNC_OPERATION;
+}
+export function resolvePullSyncReadiness(args) {
+    const baseReadiness = resolveBaseSyncReadiness(args);
+    if (baseReadiness)
+        return baseReadiness;
+    if (args.repairModeActive && !args.repairModeBypass) {
+        return blockSyncOperation('repair-active');
+    }
+    if (args.workspaceSyncPhase === 'provision-local') {
+        return blockSyncOperation('provision-local');
+    }
+    if (args.retryPending) {
+        return blockSyncOperation('retry-pending');
+    }
+    if (!args.isAuthenticated) {
+        return blockSyncOperation('auth-required');
+    }
+    if (args.pullInFlight) {
+        return blockSyncOperation('pull-in-flight');
+    }
+    if (args.pushInFlight) {
+        return blockSyncOperation('push-in-flight');
+    }
+    return ALLOW_SYNC_OPERATION;
+}
+export function resolveRetrySyncReadiness(args) {
+    const baseReadiness = resolveBaseSyncReadiness(args, { requireValidWorkspace: false });
+    if (baseReadiness)
+        return baseReadiness;
+    if (!args.isAuthenticated) {
+        return blockSyncOperation('auth-required');
+    }
+    return ALLOW_SYNC_OPERATION;
+}
+export function createWorkspaceSyncLeaseHeldDecision(operation) {
+    return blockSyncOperation('lease-held', { retainPendingSignature: operation === 'push' });
+}

package/dist/hooks/sync/controlPlane.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/sync/controlPlane.test.js

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import { createWorkspaceSyncLeaseHeldDecision, resolvePullSyncReadiness, resolvePushSyncReadiness, resolveRetrySyncReadiness, } from './controlPlane';
+const makeBaseArgs = () => ({
+    cloudAuthConfigured: true,
+    runtimeMode: 'local',
+    workspaceCloudSyncEnabled: true,
+    currentWorkspaceId: 'workspace-123',
+    isAuthenticated: true
+});
+describe('sync control plane', () => {
+    it('blocks push during repair and retains the pending signature', () => {
+        expect(resolvePushSyncReadiness({
+            ...makeBaseArgs(),
+            workspaceSyncPhase: 'active',
+            repairModeActive: true,
+            repairModeBypass: false,
+            pushInFlight: false,
+            pullInFlight: false
+        })).toEqual({
+            allowed: false,
+            reason: 'repair-active',
+            retainPendingSignature: true
+        });
+    });
+    it('allows repair push to bypass the repair-active gate', () => {
+        expect(resolvePushSyncReadiness({
+            ...makeBaseArgs(),
+            workspaceSyncPhase: 'active',
+            repairModeActive: true,
+            repairModeBypass: true,
+            pushInFlight: false,
+            pullInFlight: false
+        })).toEqual({ allowed: true });
+    });
+    it('blocks push during attach-cloud and retains the pending signature', () => {
+        expect(resolvePushSyncReadiness({
+            ...makeBaseArgs(),
+            workspaceSyncPhase: 'attach-cloud',
+            repairModeActive: false,
+            repairModeBypass: false,
+            pushInFlight: false,
+            pullInFlight: false
+        })).toEqual({
+            allowed: false,
+            reason: 'attach-cloud',
+            retainPendingSignature: true
+        });
+    });
+    it('blocks pull during provision-local', () => {
+        expect(resolvePullSyncReadiness({
+            ...makeBaseArgs(),
+            workspaceSyncPhase: 'provision-local',
+            repairModeActive: false,
+            repairModeBypass: false,
+            retryPending: false,
+            pushInFlight: false,
+            pullInFlight: false
+        })).toEqual({
+            allowed: false,
+            reason: 'provision-local',
+            retainPendingSignature: false
+        });
+    });
+    it('blocks pull when a retry is already pending', () => {
+        expect(resolvePullSyncReadiness({
+            ...makeBaseArgs(),
+            workspaceSyncPhase: 'active',
+            repairModeActive: false,
+            repairModeBypass: false,
+            retryPending: true,
+            pushInFlight: false,
+            pullInFlight: false
+        })).toEqual({
+            allowed: false,
+            reason: 'retry-pending',
+            retainPendingSignature: false
+        });
+    });
+    it('surfaces auth-required for retry readiness before the session is refreshed', () => {
+        expect(resolveRetrySyncReadiness({
+            ...makeBaseArgs(),
+            isAuthenticated: false
+        })).toEqual({
+            allowed: false,
+            reason: 'auth-required',
+            retainPendingSignature: false
+        });
+    });
+    it('rejects invalid workspace ids for transfer operations', () => {
+        expect(resolvePushSyncReadiness({
+            ...makeBaseArgs(),
+            currentWorkspaceId: 'default',
+            workspaceSyncPhase: 'active',
+            repairModeActive: false,
+            repairModeBypass: false,
+            pushInFlight: false,
+            pullInFlight: false
+        })).toEqual({
+            allowed: false,
+            reason: 'invalid-workspace',
+            retainPendingSignature: false
+        });
+    });
+    it('marks lease contention as retaining the pending signature only for push', () => {
+        expect(createWorkspaceSyncLeaseHeldDecision('push')).toEqual({
+            allowed: false,
+            reason: 'lease-held',
+            retainPendingSignature: true
+        });
+        expect(createWorkspaceSyncLeaseHeldDecision('pull')).toEqual({
+            allowed: false,
+            reason: 'lease-held',
+            retainPendingSignature: false
+        });
+        expect(createWorkspaceSyncLeaseHeldDecision('repair')).toEqual({
+            allowed: false,
+            reason: 'lease-held',
+            retainPendingSignature: false
+        });
+    });
+});

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

@@ -0,0 +1,45 @@
+import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+export type WorkspaceSyncPresentationStatus = 'off' | 'syncing' | 'attention' | 'healthy';
+interface WorkspaceSyncPresentationArgs {
+    enabled: boolean;
+    phase: WorkspaceSyncPhase;
+    busy: boolean;
+    retryAt: string | null;
+    lastErrorMessage: string | null;
+}
+interface WorkspaceSyncLifecycleBaseArgs {
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    workspaceCloudSyncEnabled: boolean;
+    authSessionResolved: boolean;
+}
+interface WorkspaceSyncAutomaticPullArgs extends WorkspaceSyncLifecycleBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    lastPullAt: string | null;
+    retryPending: boolean;
+}
+interface WorkspaceSyncFullReconcileArgs extends WorkspaceSyncLifecycleBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    isAuthenticated: boolean;
+}
+interface WorkspaceSyncStartupRepairArgs extends WorkspaceSyncFullReconcileArgs {
+    alreadyRan: boolean;
+}
+interface WorkspaceSyncReactivePushArgs extends WorkspaceSyncLifecycleBaseArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    workspaceSyncReferenceSnapshotsReady: boolean;
+}
+export declare function resolveWorkspaceSyncPresentation({ enabled, phase, busy, retryAt, lastErrorMessage }: WorkspaceSyncPresentationArgs): {
+    status: WorkspaceSyncPresentationStatus;
+    summary: string;
+    recommendedAction: string;
+};
+export declare function shouldScheduleWorkspaceReactivePush(args: WorkspaceSyncReactivePushArgs): boolean;
+export declare function shouldStartWorkspacePushWatchdog(args: WorkspaceSyncReactivePushArgs): boolean;
+export declare function resolveWorkspaceAutomaticPullPolicy(args: WorkspaceSyncAutomaticPullArgs): {
+    shouldStart: boolean;
+    shouldKickOffImmediately: boolean;
+};
+export declare function shouldStartWorkspacePeriodicFullReconcile(args: WorkspaceSyncFullReconcileArgs): boolean;
+export declare function shouldRunWorkspaceStartupRepair(args: WorkspaceSyncStartupRepairArgs): boolean;
+export {};

package/dist/hooks/sync/lifecyclePolicy.js

@@ -0,0 +1,93 @@
+function canRunLocalWorkspaceSyncLifecycle(args) {
+    return args.cloudAuthConfigured
+        && args.runtimeMode === 'local'
+        && args.workspaceCloudSyncEnabled
+        && args.authSessionResolved;
+}
+export function resolveWorkspaceSyncPresentation({ enabled, phase, busy, retryAt, lastErrorMessage }) {
+    if (!enabled) {
+        return {
+            status: 'off',
+            summary: 'Sync is turned off for this workspace.',
+            recommendedAction: 'Turn on sync when you are ready to back up this workspace.'
+        };
+    }
+    if (phase === 'provision-local') {
+        return {
+            status: 'syncing',
+            summary: busy
+                ? 'Uploading this workspace to cloud for the first time.'
+                : 'Preparing the first upload to cloud.',
+            recommendedAction: 'Keep this window open while the first upload finishes. If it seems stalled, press Sync.'
+        };
+    }
+    if (phase === 'attach-cloud') {
+        return {
+            status: 'syncing',
+            summary: busy
+                ? 'Pulling the cloud workspace into this device.'
+                : 'Waiting for the first cloud pull into this device.',
+            recommendedAction: 'Keep this window open for the first cloud pull. If it does not move, press Repair.'
+        };
+    }
+    if (retryAt) {
+        return {
+            status: 'attention',
+            summary: 'Sync hit a temporary problem and will retry automatically.',
+            recommendedAction: 'Wait for the automatic retry, or press Sync to retry now.'
+        };
+    }
+    if (lastErrorMessage || phase === 'error') {
+        return {
+            status: 'attention',
+            summary: 'Sync needs attention before it can continue.',
+            recommendedAction: 'Press Sync to retry. If the same error keeps returning, press Repair.'
+        };
+    }
+    if (busy) {
+        return {
+            status: 'syncing',
+            summary: 'Sync is currently running.',
+            recommendedAction: 'No action needed.'
+        };
+    }
+    return {
+        status: 'healthy',
+        summary: 'Sync is healthy.',
+        recommendedAction: 'No action needed.'
+    };
+}
+export function shouldScheduleWorkspaceReactivePush(args) {
+    return canRunLocalWorkspaceSyncLifecycle(args)
+        && args.workspaceSyncPhase !== 'attach-cloud'
+        && args.workspaceSyncReferenceSnapshotsReady;
+}
+export function shouldStartWorkspacePushWatchdog(args) {
+    return canRunLocalWorkspaceSyncLifecycle(args)
+        && args.workspaceSyncPhase === 'active'
+        && args.workspaceSyncReferenceSnapshotsReady;
+}
+export function resolveWorkspaceAutomaticPullPolicy(args) {
+    if (!canRunLocalWorkspaceSyncLifecycle(args)) {
+        return { shouldStart: false, shouldKickOffImmediately: false };
+    }
+    if (args.workspaceSyncPhase === 'provision-local' || args.workspaceSyncPhase === 'error' || args.retryPending) {
+        return { shouldStart: false, shouldKickOffImmediately: false };
+    }
+    return {
+        shouldStart: true,
+        shouldKickOffImmediately: args.workspaceSyncPhase === 'attach-cloud' || !args.lastPullAt
+    };
+}
+export function shouldStartWorkspacePeriodicFullReconcile(args) {
+    return canRunLocalWorkspaceSyncLifecycle(args)
+        && args.isAuthenticated
+        && args.workspaceSyncPhase === 'active';
+}
+export function shouldRunWorkspaceStartupRepair(args) {
+    return canRunLocalWorkspaceSyncLifecycle(args)
+        && args.isAuthenticated
+        && args.workspaceSyncPhase !== 'provision-local'
+        && args.workspaceSyncPhase !== 'attach-cloud'
+        && !args.alreadyRan;
+}

package/dist/hooks/sync/lifecyclePolicy.test.d.ts

@@ -0,0 +1 @@
+export {};