@taskforcehq/taskforce 0.3.305 → 0.3.307

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

@@ -1,8 +1,9 @@
 import type { MutableRefObject } from 'react';
+import type { WorkspaceSyncBaselineResetReason } from '../../sync/workspaceSyncModel';
 import type { WorkspaceSyncPhase } from '../../sync/workspaceSyncState';
+type SyncEventType = 'pull' | 'handshake' | 'bootstrap' | 'apply' | 'push';
 interface CreateSyncRecoveryCoordinatorArgs {
     currentWorkspaceId: string;
-    taxonomyStateFingerprint: string;
     workspaceCloudSyncEnabled: boolean;
     workspaceSyncPhase: WorkspaceSyncPhase;
     workspaceLastPullAt: string | null;
@@ -18,12 +19,14 @@ interface CreateSyncRecoveryCoordinatorArgs {
     workspacePendingSignatureRef: MutableRefObject<string>;
     workspaceLastPushedSignatureRef: MutableRefObject<string>;
     workspaceLastPushedWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedTaskChangeKeysRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedInitiativeIdsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedInitiativeWatermarksRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedWorkstreamIdsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedWorkstreamWatermarksRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedAiProfileIdsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedAiProfileWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceLastPushedAiProfileChangeKeysRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedDocumentPathsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedDocumentWatermarksRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedAssetPathsRef: MutableRefObject<Set<string>>;
@@ -35,6 +38,7 @@ interface CreateSyncRecoveryCoordinatorArgs {
     workspaceLastPushedAnnotatedAttachmentSessionIdsRef: MutableRefObject<Set<string>>;
     workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef: MutableRefObject<Map<string, string>>;
     workspaceLastPushedTaskEventWatermarksRef: MutableRefObject<Map<string, string>>;
+    workspaceBaselineResetReasonRef: MutableRefObject<WorkspaceSyncBaselineResetReason | null>;
     bootstrapPhaseStartedAtRef: MutableRefObject<number | null>;
     bootstrapLastProgressAtRef: MutableRefObject<number | null>;
     acquireWorkspaceSyncLease: (workspaceId: string, owner: 'pull' | 'push' | 'repair') => Promise<boolean>;
@@ -43,11 +47,21 @@ interface CreateSyncRecoveryCoordinatorArgs {
     clearWorkspaceRetry: () => void;
     clearWorkspaceIssue: () => void;
     reportWorkspaceWindowContention: (operation: 'pull' | 'push' | 'repair') => void;
+    reportSyncEvent: (workspaceId: string, event: {
+        eventType: SyncEventType;
+        status: 'success' | 'error';
+        statusCode?: number;
+        errorMessage?: string;
+        changeCount?: number;
+        requestMs?: number;
+        details?: Record<string, unknown>;
+    }) => void;
     persistWorkspaceSyncPatch: (patch: {
         phase: WorkspaceSyncPhase;
         pullCursor: null;
         lastErrorMessage: null;
     }) => Promise<unknown>;
+    persistWorkspaceSyncWatermarksSnapshotBestEffort: () => boolean;
     buildWorkspaceSyncSignature: () => string;
     pullWorkspaceChangesFromCloud: (options?: {
         repairMode?: boolean;
@@ -62,7 +76,7 @@ interface CreateSyncRecoveryCoordinatorArgs {
     isAuthenticated: boolean;
     checkAuthSession: () => Promise<boolean>;
 }
-export declare function createSyncRecoveryCoordinator({ currentWorkspaceId, taxonomyStateFingerprint, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceLastPullAt, lastBootstrapPhaseRef, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspaceStartupRepairRanRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, workspacePullCursorRef, workspaceAttachBootstrapBaselineSignatureRef, workspaceCaptureAttachBootstrapBaselineRef, workspacePendingSignatureRef, workspaceLastPushedSignatureRef, workspaceLastPushedWatermarksRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease, clearWorkspaceRetry, clearWorkspaceIssue, reportWorkspaceWindowContention, persistWorkspaceSyncPatch, buildWorkspaceSyncSignature, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, cloudAuthConfigured, runtimeMode, isAuthenticated, checkAuthSession }: CreateSyncRecoveryCoordinatorArgs): {
+export declare function createSyncRecoveryCoordinator({ currentWorkspaceId, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceLastPullAt, lastBootstrapPhaseRef, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspaceStartupRepairRanRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, workspacePullCursorRef, workspaceAttachBootstrapBaselineSignatureRef, workspaceCaptureAttachBootstrapBaselineRef, workspacePendingSignatureRef, workspaceLastPushedSignatureRef, workspaceLastPushedWatermarksRef, workspaceLastPushedTaskChangeKeysRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedAiProfileChangeKeysRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, workspaceBaselineResetReasonRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease, clearWorkspaceRetry, clearWorkspaceIssue, reportWorkspaceWindowContention, reportSyncEvent, persistWorkspaceSyncPatch, persistWorkspaceSyncWatermarksSnapshotBestEffort, buildWorkspaceSyncSignature, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, cloudAuthConfigured, runtimeMode, isAuthenticated, checkAuthSession }: CreateSyncRecoveryCoordinatorArgs): {
     retryWorkspaceCloudSync: () => Promise<boolean>;
     resetWorkspaceSyncCursorAndPull: () => Promise<void>;
 };

package/dist/hooks/sync/recovery.js

@@ -1,14 +1,85 @@
 import { resolveRepairPhase } from './bootstrap';
-import { savePersistedSyncWatermarks } from './orchestratorShared';
-export function createSyncRecoveryCoordinator({ currentWorkspaceId, taxonomyStateFingerprint, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceLastPullAt, lastBootstrapPhaseRef, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspaceStartupRepairRanRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, workspacePullCursorRef, workspaceAttachBootstrapBaselineSignatureRef, workspaceCaptureAttachBootstrapBaselineRef, workspacePendingSignatureRef, workspaceLastPushedSignatureRef, workspaceLastPushedWatermarksRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease, clearWorkspaceRetry, clearWorkspaceIssue, reportWorkspaceWindowContention, persistWorkspaceSyncPatch, buildWorkspaceSyncSignature, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, cloudAuthConfigured, runtimeMode, isAuthenticated, checkAuthSession }) {
+import { resolveRetrySyncReadiness } from './controlPlane';
+function resetWorkspaceSyncStatePushBaselines(args) {
+    args.workspaceLastPushedWatermarksRef.current = new Map();
+    args.workspaceLastPushedTaskChangeKeysRef.current = new Map();
+    args.workspaceLastPushedInitiativeIdsRef.current = new Set();
+    args.workspaceLastPushedInitiativeWatermarksRef.current = new Map();
+    args.workspaceLastPushedWorkstreamIdsRef.current = new Set();
+    args.workspaceLastPushedWorkstreamWatermarksRef.current = new Map();
+    args.workspaceLastPushedAiProfileIdsRef.current = new Set();
+    args.workspaceLastPushedAiProfileWatermarksRef.current = new Map();
+    args.workspaceLastPushedAiProfileChangeKeysRef.current = new Map();
+    args.workspaceLastPushedDocumentPathsRef.current = new Set();
+    args.workspaceLastPushedDocumentWatermarksRef.current = new Map();
+    args.workspaceLastPushedAssetPathsRef.current = new Set();
+    args.workspaceLastPushedAssetWatermarksRef.current = new Map();
+    args.workspaceBaselineResetReasonRef.current = 'repair-reset';
+}
+function resetAllWorkspacePushBaselines(args) {
+    resetWorkspaceSyncStatePushBaselines(args);
+    args.workspaceLastPushedDocumentPathsRef.current = new Set();
+    args.workspaceLastPushedDocumentWatermarksRef.current = new Map();
+    args.workspaceLastPushedAssetPathsRef.current = new Set();
+    args.workspaceLastPushedAssetWatermarksRef.current = new Map();
+    args.workspaceLastPushedDocumentReviewSessionIdsRef.current = new Set();
+    args.workspaceLastPushedDocumentReviewSessionWatermarksRef.current = new Map();
+    args.workspaceLastPushedDocumentReviewCommentIdsRef.current = new Set();
+    args.workspaceLastPushedDocumentReviewCommentWatermarksRef.current = new Map();
+    args.workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set();
+    args.workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map();
+    args.workspaceLastPushedTaskEventWatermarksRef.current = new Map();
+}
+export function createSyncRecoveryCoordinator({ currentWorkspaceId, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceLastPullAt, lastBootstrapPhaseRef, workspaceRepairModeRef, workspaceForceFullAiProfilePushRef, workspaceStartupRepairRanRef, workspaceStartupFullReconcileRanRef, workspaceFullReconcileInFlightRef, workspacePullCursorRef, workspaceAttachBootstrapBaselineSignatureRef, workspaceCaptureAttachBootstrapBaselineRef, workspacePendingSignatureRef, workspaceLastPushedSignatureRef, workspaceLastPushedWatermarksRef, workspaceLastPushedTaskChangeKeysRef, workspaceLastPushedInitiativeIdsRef, workspaceLastPushedInitiativeWatermarksRef, workspaceLastPushedWorkstreamIdsRef, workspaceLastPushedWorkstreamWatermarksRef, workspaceLastPushedAiProfileIdsRef, workspaceLastPushedAiProfileWatermarksRef, workspaceLastPushedAiProfileChangeKeysRef, workspaceLastPushedDocumentPathsRef, workspaceLastPushedDocumentWatermarksRef, workspaceLastPushedAssetPathsRef, workspaceLastPushedAssetWatermarksRef, workspaceLastPushedDocumentReviewSessionIdsRef, workspaceLastPushedDocumentReviewSessionWatermarksRef, workspaceLastPushedDocumentReviewCommentIdsRef, workspaceLastPushedDocumentReviewCommentWatermarksRef, workspaceLastPushedAnnotatedAttachmentSessionIdsRef, workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef, workspaceLastPushedTaskEventWatermarksRef, workspaceBaselineResetReasonRef, bootstrapPhaseStartedAtRef, bootstrapLastProgressAtRef, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease, clearWorkspaceRetry, clearWorkspaceIssue, reportWorkspaceWindowContention, reportSyncEvent, persistWorkspaceSyncPatch, persistWorkspaceSyncWatermarksSnapshotBestEffort, buildWorkspaceSyncSignature, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, cloudAuthConfigured, runtimeMode, isAuthenticated, checkAuthSession }) {
+    const retryEventType = workspaceSyncPhase === 'provision-local'
+        ? 'push'
+        : workspaceSyncPhase === 'attach-cloud'
+            ? 'bootstrap'
+            : 'pull';
     const retryWorkspaceCloudSync = async () => {
         clearWorkspaceRetry();
-        if (!cloudAuthConfigured || runtimeMode !== 'local' || !workspaceCloudSyncEnabled)
-            return false;
-        if (!isAuthenticated) {
+        let retryReadiness = resolveRetrySyncReadiness({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            currentWorkspaceId,
+            isAuthenticated
+        });
+        if (!retryReadiness.allowed && retryReadiness.reason === 'auth-required') {
             const authed = await checkAuthSession();
-            if (!authed)
+            if (!authed) {
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: retryEventType,
+                    status: 'error',
+                    errorMessage: 'Manual sync retry blocked: sign in is required.',
+                    details: {
+                        source: 'retry.blocked',
+                        reason: 'auth-required',
+                        phase: workspaceSyncPhase
+                    }
+                });
                 return false;
+            }
+            retryReadiness = resolveRetrySyncReadiness({
+                cloudAuthConfigured,
+                runtimeMode,
+                workspaceCloudSyncEnabled,
+                currentWorkspaceId,
+                isAuthenticated: true
+            });
+        }
+        if (!retryReadiness.allowed) {
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: retryEventType,
+                status: 'error',
+                errorMessage: `Manual sync retry blocked: ${retryReadiness.reason}.`,
+                details: {
+                    source: 'retry.blocked',
+                    reason: retryReadiness.reason,
+                    phase: workspaceSyncPhase
+                }
+            });
+            return false;
         }
         workspaceForceFullAiProfilePushRef.current = true;
         if (workspaceSyncPhase === 'provision-local') {
@@ -37,60 +108,108 @@ export function createSyncRecoveryCoordinator({ currentWorkspaceId, taxonomyStat
             const reclaimed = await acquireWorkspaceSyncLease(currentWorkspaceId, 'repair');
             if (!reclaimed) {
                 reportWorkspaceWindowContention('repair');
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: 'bootstrap',
+                    status: 'error',
+                    errorMessage: 'Manual sync repair blocked because another window is already syncing this workspace.',
+                    details: {
+                        source: 'repair.blocked',
+                        reason: 'lease-held',
+                        phase: workspaceSyncPhase
+                    }
+                });
                 return;
             }
         }
+        const repairPhase = resolveRepairPhase({
+            workspaceSyncPhase,
+            lastBootstrapPhase: lastBootstrapPhaseRef.current,
+            workspaceLastPullAt
+        });
+        const shouldResetAllPushBaselines = repairPhase === 'provision-local';
+        const shouldResetSyncStatePushBaselines = repairPhase === 'active';
         clearWorkspaceRetry();
         clearWorkspaceIssue();
-        bootstrapPhaseStartedAtRef.current = null;
-        bootstrapLastProgressAtRef.current = null;
-        workspacePullCursorRef.current = null;
-        workspaceAttachBootstrapBaselineSignatureRef.current = '';
-        workspaceCaptureAttachBootstrapBaselineRef.current = false;
-        workspacePendingSignatureRef.current = '';
-        workspaceLastPushedSignatureRef.current = '';
-        workspaceLastPushedWatermarksRef.current = new Map();
-        workspaceLastPushedInitiativeIdsRef.current = new Set();
-        workspaceLastPushedInitiativeWatermarksRef.current = new Map();
-        workspaceLastPushedWorkstreamIdsRef.current = new Set();
-        workspaceLastPushedWorkstreamWatermarksRef.current = new Map();
-        workspaceLastPushedAiProfileIdsRef.current = new Set();
-        workspaceLastPushedAiProfileWatermarksRef.current = new Map();
-        workspaceLastPushedDocumentPathsRef.current = new Set();
-        workspaceLastPushedDocumentWatermarksRef.current = new Map();
-        workspaceLastPushedAssetPathsRef.current = new Set();
-        workspaceLastPushedAssetWatermarksRef.current = new Map();
-        workspaceLastPushedDocumentReviewSessionIdsRef.current = new Set();
-        workspaceLastPushedDocumentReviewSessionWatermarksRef.current = new Map();
-        workspaceLastPushedDocumentReviewCommentIdsRef.current = new Set();
-        workspaceLastPushedDocumentReviewCommentWatermarksRef.current = new Map();
-        workspaceLastPushedAnnotatedAttachmentSessionIdsRef.current = new Set();
-        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current = new Map();
-        workspaceLastPushedTaskEventWatermarksRef.current = new Map();
-        workspaceForceFullAiProfilePushRef.current = false;
-        workspaceStartupRepairRanRef.current = false;
-        workspaceStartupFullReconcileRanRef.current = false;
-        workspaceFullReconcileInFlightRef.current = false;
-        savePersistedSyncWatermarks(currentWorkspaceId, {
-            taskWatermarks: new Map(),
-            initiativeWatermarks: new Map(),
-            workstreamWatermarks: new Map(),
-            documentWatermarks: new Map(),
-            assetWatermarks: new Map(),
-            documentReviewSessionWatermarks: new Map(),
-            documentReviewCommentWatermarks: new Map(),
-            annotatedAttachmentSessionWatermarks: new Map(),
-            taskEventWatermarks: new Map(),
-            taxonomyStateFingerprint
-        });
         try {
-            if (!workspaceCloudSyncEnabled)
+            if (!workspaceCloudSyncEnabled) {
+                reportSyncEvent(currentWorkspaceId, {
+                    eventType: 'bootstrap',
+                    status: 'error',
+                    errorMessage: 'Manual sync repair blocked because workspace sync is turned off.',
+                    details: {
+                        source: 'repair.blocked',
+                        reason: 'sync-disabled',
+                        phase: workspaceSyncPhase
+                    }
+                });
                 return;
+            }
+            bootstrapPhaseStartedAtRef.current = null;
+            bootstrapLastProgressAtRef.current = null;
+            workspacePullCursorRef.current = null;
+            workspaceAttachBootstrapBaselineSignatureRef.current = '';
+            workspaceCaptureAttachBootstrapBaselineRef.current = false;
+            workspacePendingSignatureRef.current = '';
+            workspaceLastPushedSignatureRef.current = '';
+            workspaceForceFullAiProfilePushRef.current = false;
+            workspaceStartupRepairRanRef.current = false;
+            workspaceStartupFullReconcileRanRef.current = false;
+            workspaceFullReconcileInFlightRef.current = false;
+            if (shouldResetAllPushBaselines) {
+                resetAllWorkspacePushBaselines({
+                    workspaceLastPushedWatermarksRef,
+                    workspaceLastPushedTaskChangeKeysRef,
+                    workspaceLastPushedInitiativeIdsRef,
+                    workspaceLastPushedInitiativeWatermarksRef,
+                    workspaceLastPushedWorkstreamIdsRef,
+                    workspaceLastPushedWorkstreamWatermarksRef,
+                    workspaceLastPushedAiProfileIdsRef,
+                    workspaceLastPushedAiProfileWatermarksRef,
+                    workspaceLastPushedAiProfileChangeKeysRef,
+                    workspaceLastPushedDocumentPathsRef,
+                    workspaceLastPushedDocumentWatermarksRef,
+                    workspaceLastPushedAssetPathsRef,
+                    workspaceLastPushedAssetWatermarksRef,
+                    workspaceLastPushedDocumentReviewSessionIdsRef,
+                    workspaceLastPushedDocumentReviewSessionWatermarksRef,
+                    workspaceLastPushedDocumentReviewCommentIdsRef,
+                    workspaceLastPushedDocumentReviewCommentWatermarksRef,
+                    workspaceLastPushedAnnotatedAttachmentSessionIdsRef,
+                    workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef,
+                    workspaceLastPushedTaskEventWatermarksRef,
+                    workspaceBaselineResetReasonRef,
+                });
+            }
+            else if (shouldResetSyncStatePushBaselines) {
+                resetWorkspaceSyncStatePushBaselines({
+                    workspaceLastPushedWatermarksRef,
+                    workspaceLastPushedTaskChangeKeysRef,
+                    workspaceLastPushedInitiativeIdsRef,
+                    workspaceLastPushedInitiativeWatermarksRef,
+                    workspaceLastPushedWorkstreamIdsRef,
+                    workspaceLastPushedWorkstreamWatermarksRef,
+                    workspaceLastPushedAiProfileIdsRef,
+                    workspaceLastPushedAiProfileWatermarksRef,
+                    workspaceLastPushedAiProfileChangeKeysRef,
+                    workspaceLastPushedDocumentPathsRef,
+                    workspaceLastPushedDocumentWatermarksRef,
+                    workspaceLastPushedAssetPathsRef,
+                    workspaceLastPushedAssetWatermarksRef,
+                    workspaceBaselineResetReasonRef,
+                });
+            }
+            void persistWorkspaceSyncWatermarksSnapshotBestEffort();
             workspaceRepairModeRef.current = true;
-            const repairPhase = resolveRepairPhase({
-                workspaceSyncPhase,
-                lastBootstrapPhase: lastBootstrapPhaseRef.current,
-                workspaceLastPullAt
+            reportSyncEvent(currentWorkspaceId, {
+                eventType: 'bootstrap',
+                status: 'success',
+                errorMessage: 'Manual sync repair started.',
+                details: {
+                    source: 'repair.started',
+                    phase: workspaceSyncPhase,
+                    repairPhase,
+                    lastBootstrapPhase: lastBootstrapPhaseRef.current
+                }
             });
             await persistWorkspaceSyncPatch({
                 phase: repairPhase,
@@ -104,7 +223,14 @@ export function createSyncRecoveryCoordinator({ currentWorkspaceId, taxonomyStat
                 await pushWorkspaceChangesToCloud(signature, { forceAllAiProfiles: true, repairMode: true });
                 return;
             }
-            await pullWorkspaceChangesFromCloud({ repairMode: true });
+            const pulled = await pullWorkspaceChangesFromCloud({ repairMode: true });
+            if (repairPhase !== 'active' || !pulled)
+                return;
+            const signature = buildWorkspaceSyncSignature();
+            if (!signature)
+                return;
+            workspacePendingSignatureRef.current = signature;
+            await pushWorkspaceChangesToCloud(signature, { forceAllAiProfiles: true, repairMode: true });
         }
         finally {
             workspaceRepairModeRef.current = false;

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

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

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

@@ -0,0 +1,292 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createSyncRecoveryCoordinator } from './recovery';
+import { readPersistedSyncWatermarks, savePersistedSyncWatermarks } from './orchestratorShared';
+function createRef(initial) {
+    return { current: initial };
+}
+function createCoordinator(overrides) {
+    const pullWorkspaceChangesFromCloud = vi.fn(async () => true);
+    const pushWorkspaceChangesToCloud = vi.fn(async () => true);
+    const checkAuthSession = vi.fn(async () => true);
+    const reportSyncEvent = vi.fn();
+    const args = {
+        currentWorkspaceId: 'workspace-local-active',
+        workspaceCloudSyncEnabled: true,
+        workspaceSyncPhase: 'active',
+        workspaceLastPullAt: '2026-03-15T18:00:00.000Z',
+        lastBootstrapPhaseRef: createRef('active'),
+        workspaceRepairModeRef: createRef(false),
+        workspaceForceFullAiProfilePushRef: createRef(false),
+        workspaceStartupRepairRanRef: createRef(true),
+        workspaceStartupFullReconcileRanRef: createRef(true),
+        workspaceFullReconcileInFlightRef: createRef(false),
+        workspacePullCursorRef: createRef('cursor-1'),
+        workspaceAttachBootstrapBaselineSignatureRef: createRef(''),
+        workspaceCaptureAttachBootstrapBaselineRef: createRef(false),
+        workspacePendingSignatureRef: createRef(''),
+        workspaceLastPushedSignatureRef: createRef(''),
+        workspaceLastPushedWatermarksRef: createRef(new Map()),
+        workspaceLastPushedTaskChangeKeysRef: createRef(new Map()),
+        workspaceLastPushedInitiativeIdsRef: createRef(new Set()),
+        workspaceLastPushedInitiativeWatermarksRef: createRef(new Map()),
+        workspaceLastPushedWorkstreamIdsRef: createRef(new Set()),
+        workspaceLastPushedWorkstreamWatermarksRef: createRef(new Map()),
+        workspaceLastPushedAiProfileIdsRef: createRef(new Set()),
+        workspaceLastPushedAiProfileWatermarksRef: createRef(new Map()),
+        workspaceLastPushedAiProfileChangeKeysRef: createRef(new Map()),
+        workspaceLastPushedDocumentPathsRef: createRef(new Set()),
+        workspaceLastPushedDocumentWatermarksRef: createRef(new Map()),
+        workspaceLastPushedAssetPathsRef: createRef(new Set()),
+        workspaceLastPushedAssetWatermarksRef: createRef(new Map()),
+        workspaceLastPushedDocumentReviewSessionIdsRef: createRef(new Set()),
+        workspaceLastPushedDocumentReviewSessionWatermarksRef: createRef(new Map()),
+        workspaceLastPushedDocumentReviewCommentIdsRef: createRef(new Set()),
+        workspaceLastPushedDocumentReviewCommentWatermarksRef: createRef(new Map()),
+        workspaceLastPushedAnnotatedAttachmentSessionIdsRef: createRef(new Set()),
+        workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef: createRef(new Map()),
+        workspaceLastPushedTaskEventWatermarksRef: createRef(new Map()),
+        workspaceBaselineResetReasonRef: createRef(null),
+        bootstrapPhaseStartedAtRef: createRef(null),
+        bootstrapLastProgressAtRef: createRef(null),
+        acquireWorkspaceSyncLease: vi.fn(async () => true),
+        releaseWorkspaceSyncLease: vi.fn(),
+        forceClearWorkspaceSyncLease: vi.fn(),
+        clearWorkspaceRetry: vi.fn(),
+        clearWorkspaceIssue: vi.fn(),
+        reportWorkspaceWindowContention: vi.fn(),
+        reportSyncEvent,
+        persistWorkspaceSyncPatch: vi.fn(async () => undefined),
+        persistWorkspaceSyncWatermarksSnapshotBestEffort: vi.fn(() => true),
+        buildWorkspaceSyncSignature: vi.fn(() => 'signature-1'),
+        pullWorkspaceChangesFromCloud,
+        pushWorkspaceChangesToCloud,
+        cloudAuthConfigured: true,
+        runtimeMode: 'local',
+        isAuthenticated: true,
+        checkAuthSession,
+        ...overrides
+    };
+    const persistWorkspaceSyncWatermarksSnapshotBestEffort = vi.fn(() => savePersistedSyncWatermarks(args.currentWorkspaceId, {
+        taskIds: new Set(args.workspaceLastPushedWatermarksRef.current.keys()),
+        taskWatermarks: args.workspaceLastPushedWatermarksRef.current,
+        taskChangeKeys: args.workspaceLastPushedTaskChangeKeysRef.current,
+        initiativeWatermarks: args.workspaceLastPushedInitiativeWatermarksRef.current,
+        workstreamWatermarks: args.workspaceLastPushedWorkstreamWatermarksRef.current,
+        aiProfileWatermarks: args.workspaceLastPushedAiProfileWatermarksRef.current,
+        aiProfileChangeKeys: args.workspaceLastPushedAiProfileChangeKeysRef.current,
+        documentWatermarks: args.workspaceLastPushedDocumentWatermarksRef.current,
+        assetWatermarks: args.workspaceLastPushedAssetWatermarksRef.current,
+        documentReviewSessionWatermarks: args.workspaceLastPushedDocumentReviewSessionWatermarksRef.current,
+        documentReviewCommentWatermarks: args.workspaceLastPushedDocumentReviewCommentWatermarksRef.current,
+        annotatedAttachmentSessionWatermarks: args.workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef.current,
+        taskEventWatermarks: args.workspaceLastPushedTaskEventWatermarksRef.current,
+        taxonomyStateFingerprint: 'taxonomy-fingerprint-1'
+    }));
+    args.persistWorkspaceSyncWatermarksSnapshotBestEffort = persistWorkspaceSyncWatermarksSnapshotBestEffort;
+    return {
+        coordinator: createSyncRecoveryCoordinator(args),
+        args,
+        pullWorkspaceChangesFromCloud,
+        pushWorkspaceChangesToCloud,
+        checkAuthSession,
+        reportSyncEvent,
+        persistWorkspaceSyncWatermarksSnapshotBestEffort
+    };
+}
+describe('createSyncRecoveryCoordinator', () => {
+    beforeEach(() => {
+        localStorage.clear();
+    });
+    it('retries provision-local by pushing only with a forced AI profile sync', async () => {
+        const { coordinator, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud } = createCoordinator({
+            workspaceSyncPhase: 'provision-local'
+        });
+        const result = await coordinator.retryWorkspaceCloudSync();
+        expect(result).toBe(true);
+        expect(pullWorkspaceChangesFromCloud).not.toHaveBeenCalled();
+        expect(pushWorkspaceChangesToCloud).toHaveBeenCalledWith('signature-1', { forceAllAiProfiles: true });
+    });
+    it('retries attach-cloud by pulling only without pushing local state', async () => {
+        const { coordinator, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud } = createCoordinator({
+            workspaceSyncPhase: 'attach-cloud'
+        });
+        const result = await coordinator.retryWorkspaceCloudSync();
+        expect(result).toBe(true);
+        expect(pullWorkspaceChangesFromCloud).toHaveBeenCalledTimes(1);
+        expect(pushWorkspaceChangesToCloud).not.toHaveBeenCalled();
+    });
+    it('retries active sync by pulling first and then pushing the latest signature', async () => {
+        const { coordinator, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, args, reportSyncEvent } = createCoordinator({
+            workspaceSyncPhase: 'active'
+        });
+        const result = await coordinator.retryWorkspaceCloudSync();
+        expect(result).toBe(true);
+        expect(pullWorkspaceChangesFromCloud).toHaveBeenCalledTimes(1);
+        expect(pushWorkspaceChangesToCloud).toHaveBeenCalledWith('signature-1', { forceAllAiProfiles: true });
+        expect(args.workspacePendingSignatureRef.current).toBe('signature-1');
+        expect(reportSyncEvent).not.toHaveBeenCalled();
+    });
+    it('reports blocked manual retry reasons when auth cannot be refreshed', async () => {
+        const { coordinator, checkAuthSession, reportSyncEvent, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud } = createCoordinator({
+            workspaceSyncPhase: 'active',
+            isAuthenticated: false
+        });
+        checkAuthSession.mockResolvedValue(false);
+        const result = await coordinator.retryWorkspaceCloudSync();
+        expect(result).toBe(false);
+        expect(pullWorkspaceChangesFromCloud).not.toHaveBeenCalled();
+        expect(pushWorkspaceChangesToCloud).not.toHaveBeenCalled();
+        expect(reportSyncEvent).toHaveBeenCalledWith('workspace-local-active', expect.objectContaining({
+            eventType: 'pull',
+            status: 'error',
+            errorMessage: 'Manual sync retry blocked: sign in is required.',
+            details: expect.objectContaining({
+                source: 'retry.blocked',
+                reason: 'auth-required',
+                phase: 'active'
+            })
+        }));
+    });
+    it('reports repair start metadata before entering recovery mode', async () => {
+        const { coordinator, reportSyncEvent, args } = createCoordinator({
+            workspaceSyncPhase: 'error',
+            lastBootstrapPhaseRef: createRef('attach-cloud'),
+            workspaceLastPullAt: null
+        });
+        await coordinator.resetWorkspaceSyncCursorAndPull();
+        expect(reportSyncEvent).toHaveBeenCalledWith('workspace-local-active', expect.objectContaining({
+            eventType: 'bootstrap',
+            status: 'success',
+            errorMessage: 'Manual sync repair started.',
+            details: expect.objectContaining({
+                source: 'repair.started',
+                phase: 'error',
+                repairPhase: 'attach-cloud',
+                lastBootstrapPhase: 'attach-cloud'
+            })
+        }));
+        expect(args.workspaceBaselineResetReasonRef.current).toBeNull();
+        expect(args.workspaceRepairModeRef.current).toBe(false);
+    });
+    it('resets sync-state and content push baselines during active repair', async () => {
+        const taskWatermarks = new Map([['task-1', '2026-03-15T17:00:00.000Z']]);
+        const taskChangeKeys = new Map([['task-1', 'task-change-key-1']]);
+        const initiativeWatermarks = new Map([['initiative-1', '2026-03-15T17:00:00.000Z']]);
+        const workstreamWatermarks = new Map([['workstream-1', '2026-03-15T17:00:00.000Z']]);
+        const aiProfileWatermarks = new Map([['profile-1', '2026-03-15T17:00:00.000Z']]);
+        const aiProfileChangeKeys = new Map([['profile-1', 'ai-profile-change-key-1']]);
+        const documentWatermarks = new Map([['docs/spec.md', '2026-03-15T17:00:00.000Z']]);
+        const assetWatermarks = new Map([['assets/image.png', '2026-03-15T17:00:00.000Z']]);
+        const reviewSessionWatermarks = new Map([['review-1', '2026-03-15T17:00:00.000Z']]);
+        const reviewCommentWatermarks = new Map([['comment-1', '2026-03-15T17:00:00.000Z']]);
+        const annotatedWatermarks = new Map([['annotated-1', '2026-03-15T17:00:00.000Z']]);
+        const taskEventWatermarks = new Map([['event-1', '2026-03-15T17:00:00.000Z']]);
+        const { coordinator, args, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud } = createCoordinator({
+            workspaceSyncPhase: 'active',
+            workspaceLastPullAt: '2026-03-15T18:00:00.000Z',
+            workspaceLastPushedWatermarksRef: createRef(taskWatermarks),
+            workspaceLastPushedTaskChangeKeysRef: createRef(taskChangeKeys),
+            workspaceLastPushedInitiativeIdsRef: createRef(new Set(['initiative-1'])),
+            workspaceLastPushedInitiativeWatermarksRef: createRef(initiativeWatermarks),
+            workspaceLastPushedWorkstreamIdsRef: createRef(new Set(['workstream-1'])),
+            workspaceLastPushedWorkstreamWatermarksRef: createRef(workstreamWatermarks),
+            workspaceLastPushedAiProfileIdsRef: createRef(new Set(['profile-1'])),
+            workspaceLastPushedAiProfileWatermarksRef: createRef(aiProfileWatermarks),
+            workspaceLastPushedAiProfileChangeKeysRef: createRef(aiProfileChangeKeys),
+            workspaceLastPushedDocumentPathsRef: createRef(new Set(['docs/spec.md'])),
+            workspaceLastPushedDocumentWatermarksRef: createRef(documentWatermarks),
+            workspaceLastPushedAssetPathsRef: createRef(new Set(['assets/image.png'])),
+            workspaceLastPushedAssetWatermarksRef: createRef(assetWatermarks),
+            workspaceLastPushedDocumentReviewSessionIdsRef: createRef(new Set(['review-1'])),
+            workspaceLastPushedDocumentReviewSessionWatermarksRef: createRef(reviewSessionWatermarks),
+            workspaceLastPushedDocumentReviewCommentIdsRef: createRef(new Set(['comment-1'])),
+            workspaceLastPushedDocumentReviewCommentWatermarksRef: createRef(reviewCommentWatermarks),
+            workspaceLastPushedAnnotatedAttachmentSessionIdsRef: createRef(new Set(['annotated-1'])),
+            workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef: createRef(annotatedWatermarks),
+            workspaceLastPushedTaskEventWatermarksRef: createRef(taskEventWatermarks),
+        });
+        await coordinator.resetWorkspaceSyncCursorAndPull();
+        expect(args.workspaceBaselineResetReasonRef.current).toBe('repair-reset');
+        expect(args.workspaceLastPushedWatermarksRef.current.size).toBe(0);
+        expect(args.workspaceLastPushedTaskChangeKeysRef.current.size).toBe(0);
+        expect(args.workspaceLastPushedInitiativeWatermarksRef.current.size).toBe(0);
+        expect(args.workspaceLastPushedWorkstreamWatermarksRef.current.size).toBe(0);
+        expect(args.workspaceLastPushedAiProfileWatermarksRef.current.size).toBe(0);
+        expect(args.workspaceLastPushedAiProfileChangeKeysRef.current.size).toBe(0);
+        expect(args.workspaceLastPushedDocumentWatermarksRef.current.size).toBe(0);
+        expect(args.workspaceLastPushedAssetWatermarksRef.current.size).toBe(0);
+        expect(pullWorkspaceChangesFromCloud).toHaveBeenCalledWith({ repairMode: true });
+        expect(pushWorkspaceChangesToCloud).toHaveBeenCalledWith('signature-1', {
+            forceAllAiProfiles: true,
+            repairMode: true
+        });
+        const persisted = readPersistedSyncWatermarks('workspace-local-active', 'taxonomy-fingerprint-1');
+        expect(persisted?.taskWatermarks.size).toBe(0);
+        expect(persisted?.taskChangeKeys?.size).toBe(0);
+        expect(persisted?.initiativeWatermarks.size).toBe(0);
+        expect(persisted?.workstreamWatermarks.size).toBe(0);
+        expect(persisted?.aiProfileWatermarks.size).toBe(0);
+        expect(persisted?.aiProfileChangeKeys?.size).toBe(0);
+        expect(persisted?.documentWatermarks.size).toBe(0);
+        expect(persisted?.assetWatermarks.size).toBe(0);
+        expect(persisted?.taskEventWatermarks.get('event-1')).toBe('2026-03-15T17:00:00.000Z');
+    });
+    it('does not push during attach-cloud repair', async () => {
+        const { coordinator, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud } = createCoordinator({
+            workspaceSyncPhase: 'attach-cloud',
+            workspaceLastPullAt: null
+        });
+        await coordinator.resetWorkspaceSyncCursorAndPull();
+        expect(pullWorkspaceChangesFromCloud).toHaveBeenCalledWith({ repairMode: true });
+        expect(pushWorkspaceChangesToCloud).not.toHaveBeenCalled();
+    });
+    it('fully resets push baselines for provision-local repair', async () => {
+        const { coordinator, args } = createCoordinator({
+            workspaceSyncPhase: 'error',
+            workspaceLastPullAt: null,
+            lastBootstrapPhaseRef: createRef('provision-local'),
+            workspaceLastPushedWatermarksRef: createRef(new Map([['task-1', '2026-03-15T17:00:00.000Z']])),
+            workspaceLastPushedInitiativeIdsRef: createRef(new Set(['initiative-1'])),
+            workspaceLastPushedInitiativeWatermarksRef: createRef(new Map([['initiative-1', '2026-03-15T17:00:00.000Z']])),
+            workspaceLastPushedWorkstreamIdsRef: createRef(new Set(['workstream-1'])),
+            workspaceLastPushedWorkstreamWatermarksRef: createRef(new Map([['workstream-1', '2026-03-15T17:00:00.000Z']])),
+            workspaceLastPushedAiProfileIdsRef: createRef(new Set(['profile-1'])),
+            workspaceLastPushedAiProfileWatermarksRef: createRef(new Map([['profile-1', '2026-03-15T17:00:00.000Z']])),
+            workspaceLastPushedDocumentPathsRef: createRef(new Set(['docs/spec.md'])),
+            workspaceLastPushedDocumentWatermarksRef: createRef(new Map([['docs/spec.md', '2026-03-15T17:00:00.000Z']])),
+            workspaceLastPushedAssetPathsRef: createRef(new Set(['assets/image.png'])),
+            workspaceLastPushedAssetWatermarksRef: createRef(new Map([['assets/image.png', '2026-03-15T17:00:00.000Z']])),
+            workspaceLastPushedDocumentReviewSessionIdsRef: createRef(new Set(['review-1'])),
+            workspaceLastPushedDocumentReviewSessionWatermarksRef: createRef(new Map([['review-1', '2026-03-15T17:00:00.000Z']])),
+            workspaceLastPushedDocumentReviewCommentIdsRef: createRef(new Set(['comment-1'])),
+            workspaceLastPushedDocumentReviewCommentWatermarksRef: createRef(new Map([['comment-1', '2026-03-15T17:00:00.000Z']])),
+            workspaceLastPushedAnnotatedAttachmentSessionIdsRef: createRef(new Set(['annotated-1'])),
+            workspaceLastPushedAnnotatedAttachmentSessionWatermarksRef: createRef(new Map([['annotated-1', '2026-03-15T17:00:00.000Z']])),
+            workspaceLastPushedTaskEventWatermarksRef: createRef(new Map([['event-1', '2026-03-15T17:00:00.000Z']])),
+        });
+        await coordinator.resetWorkspaceSyncCursorAndPull();
+        expect(args.workspaceBaselineResetReasonRef.current).toBe('repair-reset');
+        expect(args.workspaceLastPushedWatermarksRef.current.size).toBe(0);
+        expect(args.workspaceLastPushedDocumentWatermarksRef.current.size).toBe(0);
+        expect(args.workspaceLastPushedAssetWatermarksRef.current.size).toBe(0);
+        const persisted = readPersistedSyncWatermarks('workspace-local-active', 'taxonomy-fingerprint-1');
+        expect(persisted?.taskWatermarks.size).toBe(0);
+        expect(persisted?.documentWatermarks.size).toBe(0);
+        expect(persisted?.assetWatermarks.size).toBe(0);
+    });
+    it('does not clear push baselines when repair is blocked because sync is disabled', async () => {
+        const taskWatermarks = new Map([['task-1', '2026-03-15T17:00:00.000Z']]);
+        const { coordinator, args, reportSyncEvent } = createCoordinator({
+            workspaceCloudSyncEnabled: false,
+            workspaceLastPushedWatermarksRef: createRef(taskWatermarks)
+        });
+        await coordinator.resetWorkspaceSyncCursorAndPull();
+        expect(args.workspaceLastPushedWatermarksRef.current).toBe(taskWatermarks);
+        expect(readPersistedSyncWatermarks('workspace-local-active', 'taxonomy-fingerprint-1')).toBeNull();
+        expect(reportSyncEvent).toHaveBeenCalledWith('workspace-local-active', expect.objectContaining({
+            eventType: 'bootstrap',
+            status: 'error',
+            errorMessage: 'Manual sync repair blocked because workspace sync is turned off.'
+        }));
+    });
+});