@taskforcehq/taskforce 0.3.304 → 0.3.306

package/dist/hooks/auth/useTaskforceAuthBootstrap.js

@@ -1,6 +1,10 @@
 import { useCallback, useEffect } from 'react';
 import { createDefaultAssigneeOptions } from '../../utils/assignees';
+import { logBootstrapDebug } from '../workspace/workspaceLocalState';
 import { persistLocalMutationActorUserId, readLocalMutationActorUserId } from '../../utils/taskforceApiClient';
+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 +45,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)
                 : 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 +72,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 +84,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 +132,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 +151,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/sync/auth.js

@@ -49,7 +49,9 @@ export function createSyncAuthCoordinator({ currentWorkspaceId, workspaceSyncPha
         if (ensured.transient || isTransientWorkspaceSyncStatus(ensured.statusCode)) {
             scheduleWorkspaceSyncRetry(ensured.retryAfterMs);
         }
-        else if (workspaceSyncPhase === 'active') {
+        else if (workspaceSyncPhase === 'active'
+            || workspaceSyncPhase === 'attach-cloud'
+            || workspaceSyncPhase === 'provision-local') {
             persistWorkspaceSyncPatchSafely({ phase: 'error', lastErrorMessage: message });
         }
         return false;

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

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

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+import { resolveWorkspaceAutomaticPullPolicy, resolveWorkspaceSyncPresentation, shouldRunWorkspaceStartupRepair, shouldScheduleWorkspaceReactivePush, shouldStartWorkspacePeriodicFullReconcile, shouldStartWorkspacePushWatchdog, } from './lifecyclePolicy';
+const makeLifecycleBaseArgs = () => ({
+    cloudAuthConfigured: true,
+    runtimeMode: 'local',
+    workspaceCloudSyncEnabled: true,
+    authSessionResolved: true
+});
+describe('sync lifecycle policy', () => {
+    it('reports bootstrap phases as syncing with phase-specific guidance', () => {
+        expect(resolveWorkspaceSyncPresentation({
+            enabled: true,
+            phase: 'attach-cloud',
+            busy: false,
+            retryAt: null,
+            lastErrorMessage: null
+        })).toEqual({
+            status: 'syncing',
+            summary: '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.'
+        });
+    });
+    it('reports retry state as attention even when sync is otherwise idle', () => {
+        expect(resolveWorkspaceSyncPresentation({
+            enabled: true,
+            phase: 'active',
+            busy: false,
+            retryAt: '2026-04-18T16:00:00.000Z',
+            lastErrorMessage: null
+        })).toEqual({
+            status: 'attention',
+            summary: 'Sync hit a temporary problem and will retry automatically.',
+            recommendedAction: 'Wait for the automatic retry, or press Sync to retry now.'
+        });
+    });
+    it('allows reactive push only after bootstrap and reference snapshots are ready', () => {
+        expect(shouldScheduleWorkspaceReactivePush({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            workspaceSyncReferenceSnapshotsReady: true
+        })).toBe(true);
+        expect(shouldScheduleWorkspaceReactivePush({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'attach-cloud',
+            workspaceSyncReferenceSnapshotsReady: true
+        })).toBe(false);
+        expect(shouldScheduleWorkspaceReactivePush({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            workspaceSyncReferenceSnapshotsReady: false
+        })).toBe(false);
+    });
+    it('starts the push watchdog only for active sync', () => {
+        expect(shouldStartWorkspacePushWatchdog({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            workspaceSyncReferenceSnapshotsReady: true
+        })).toBe(true);
+        expect(shouldStartWorkspacePushWatchdog({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'error',
+            workspaceSyncReferenceSnapshotsReady: true
+        })).toBe(false);
+    });
+    it('starts automatic pull for attach-cloud and kickstarts first active pull when no pull has succeeded yet', () => {
+        expect(resolveWorkspaceAutomaticPullPolicy({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'attach-cloud',
+            lastPullAt: null,
+            retryPending: false
+        })).toEqual({
+            shouldStart: true,
+            shouldKickOffImmediately: true
+        });
+        expect(resolveWorkspaceAutomaticPullPolicy({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            lastPullAt: null,
+            retryPending: false
+        })).toEqual({
+            shouldStart: true,
+            shouldKickOffImmediately: true
+        });
+        expect(resolveWorkspaceAutomaticPullPolicy({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            lastPullAt: '2026-04-18T15:00:00.000Z',
+            retryPending: true
+        })).toEqual({
+            shouldStart: false,
+            shouldKickOffImmediately: false
+        });
+    });
+    it('runs periodic full reconcile and startup repair only in authenticated active sync', () => {
+        expect(shouldStartWorkspacePeriodicFullReconcile({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            isAuthenticated: true
+        })).toBe(true);
+        expect(shouldStartWorkspacePeriodicFullReconcile({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'attach-cloud',
+            isAuthenticated: true
+        })).toBe(false);
+        expect(shouldRunWorkspaceStartupRepair({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            isAuthenticated: true,
+            alreadyRan: false
+        })).toBe(true);
+        expect(shouldRunWorkspaceStartupRepair({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'error',
+            isAuthenticated: true,
+            alreadyRan: false
+        })).toBe(true);
+        expect(shouldRunWorkspaceStartupRepair({
+            ...makeLifecycleBaseArgs(),
+            workspaceSyncPhase: 'active',
+            isAuthenticated: true,
+            alreadyRan: true
+        })).toBe(false);
+    });
+});

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

@@ -1,5 +1,6 @@
 import type { WorkspaceTaxonomyState } from '../../shared/taxonomyState.js';
 import type { WorkspaceSyncAiProfileSnapshot, WorkspaceSyncDocumentReviewCommentSnapshot, WorkspaceSyncDocumentReviewSessionSnapshot, WorkspaceSyncTaskEventSnapshot } from '../../sync/workspaceSyncModel';
+import type { WorkspaceSyncPushBaselineSnapshot } from '../../sync/workspaceSyncState.js';
 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";
@@ -20,9 +21,13 @@ export declare function buildTaxonomyStateFingerprint(taxonomyState?: WorkspaceT
 export declare function flattenDocumentReviewComments(sessions: WorkspaceSyncDocumentReviewSessionSnapshot[]): WorkspaceSyncDocumentReviewCommentSnapshot[];
 export declare function flattenTaskEvents(tasks: TaskItem[], archivedTasks: TaskItem[]): WorkspaceSyncTaskEventSnapshot[];
 export interface PersistedSyncWatermarks {
+    taskIds: Set<string>;
     taskWatermarks: Map<string, string>;
+    taskChangeKeys?: Map<string, string>;
     initiativeWatermarks: Map<string, string>;
     workstreamWatermarks: Map<string, string>;
+    aiProfileWatermarks: Map<string, string>;
+    aiProfileChangeKeys?: Map<string, string>;
     documentWatermarks: Map<string, string>;
     assetWatermarks: Map<string, string>;
     documentReviewSessionWatermarks: Map<string, string>;
@@ -30,7 +35,11 @@ export interface PersistedSyncWatermarks {
     annotatedAttachmentSessionWatermarks: Map<string, string>;
     taskEventWatermarks: Map<string, string>;
 }
+export declare function buildPersistedSyncWatermarksSnapshot(data: PersistedSyncWatermarks & {
+    taxonomyStateFingerprint?: string;
+}): WorkspaceSyncPushBaselineSnapshot;
+export declare function parsePersistedSyncWatermarksSnapshot(snapshot: WorkspaceSyncPushBaselineSnapshot | null | undefined, taxonomyStateFingerprint?: string): PersistedSyncWatermarks | null;
 export declare function readPersistedSyncWatermarks(workspaceId: string, taxonomyStateFingerprint?: string): PersistedSyncWatermarks | null;
 export declare function savePersistedSyncWatermarks(workspaceId: string, data: PersistedSyncWatermarks & {
     taxonomyStateFingerprint?: string;
-}): void;
+}): boolean;