@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/sync/engine/workspaceSyncEngineLocalServices.js

@@ -0,0 +1,25 @@
+import { applyLocalWorkspaceChanges, applyLocalWorkspaceSyncV3CombinedProjection, applyLocalWorkspaceSyncV3Projection, applyLocalWorkspaceSyncV3TaskCommentAudit, completeLocalSyncAuthoritativeRepair, getLocalWorkspaceContentPullObligations, recordLocalWorkspaceContentPullObligationFailures, getLocalTaskMetadataOwnership, getLocalWorkspaceContentManifest, getLocalWorkspaceSyncV3CombinedProjection, getLocalWorkspaceSyncV3Projection, getLocalWorkspaceSyncV3TaskCommentAudit, } from '../cloudSyncApi.js';
+import { prepareLocalTaskRootOutboxRecovery, } from '../v3/localOutboxRecoveryClient.js';
+/**
+ * Same-origin HTTP implementation used while the browser owns orchestration.
+ */
+export function createBrowserWorkspaceSyncEngineLocalServices(options = {}) {
+    return {
+        readPushOwnership: getLocalTaskMetadataOwnership,
+        readContentManifest: getLocalWorkspaceContentManifest,
+        applyV2Batch: applyLocalWorkspaceChanges,
+        listContentPullObligations: getLocalWorkspaceContentPullObligations,
+        recordContentPullObligationFailures: recordLocalWorkspaceContentPullObligationFailures,
+        readInitiativeProjection: getLocalWorkspaceSyncV3Projection,
+        applyInitiativeProjection: applyLocalWorkspaceSyncV3Projection,
+        readCombinedProjection: getLocalWorkspaceSyncV3CombinedProjection,
+        applyCombinedProjection: applyLocalWorkspaceSyncV3CombinedProjection,
+        readTaskCommentAuditCursor: getLocalWorkspaceSyncV3TaskCommentAudit,
+        applyTaskCommentAuditPage: applyLocalWorkspaceSyncV3TaskCommentAudit,
+        prepareOutboxRecovery: (workspaceId) => prepareLocalTaskRootOutboxRecovery({
+            workspaceId,
+            ...(options.recoveryFetchImpl ? { fetchImpl: options.recoveryFetchImpl } : {}),
+        }),
+        completeAuthoritativeRepair: completeLocalSyncAuthoritativeRepair,
+    };
+}

package/dist/sync/engine/workspaceSyncEngineParity.d.ts

@@ -0,0 +1,8 @@
+export declare const WORKSPACE_SYNC_ENGINE_PARITY_CORPUS_VERSION: 1;
+export interface WorkspaceSyncEngineParityFixture<TInput, TOutput> {
+    corpusVersion: typeof WORKSPACE_SYNC_ENGINE_PARITY_CORPUS_VERSION;
+    name: string;
+    input: TInput;
+    expected: TOutput;
+}
+export declare function replayWorkspaceSyncEngineParityFixture<TInput, TOutput>(fixture: WorkspaceSyncEngineParityFixture<TInput, TOutput>, evaluate: (input: TInput) => TOutput): TOutput;

package/dist/sync/engine/workspaceSyncEngineParity.js

@@ -0,0 +1,7 @@
+export const WORKSPACE_SYNC_ENGINE_PARITY_CORPUS_VERSION = 1;
+export function replayWorkspaceSyncEngineParityFixture(fixture, evaluate) {
+    if (fixture.corpusVersion !== WORKSPACE_SYNC_ENGINE_PARITY_CORPUS_VERSION) {
+        throw new Error('Unsupported workspace sync engine parity corpus version.');
+    }
+    return evaluate(fixture.input);
+}

package/dist/sync/engine/workspaceSyncEnginePullPolicy.d.ts

@@ -0,0 +1,32 @@
+import type { WorkspaceSyncPhase } from '../workspaceSyncState.js';
+export interface WorkspacePullRequestPlan {
+    bootstrap: boolean;
+    cursor: string | null;
+    successEventType: 'bootstrap' | 'pull';
+}
+interface ResolveWorkspacePullRequestPlanArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    forceCursorNull?: boolean;
+    currentCursor: string | null;
+}
+interface ResolveWorkspacePullSuccessPlanArgs {
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    forceCursorNull?: boolean;
+    repairMode?: boolean;
+    startupFullReconcileRan: boolean;
+    pendingSignature: string;
+    fallbackSignature: string;
+    lastPushedSignature: string;
+}
+export interface WorkspacePullSuccessPlan {
+    successEventType: 'bootstrap' | 'pull';
+    shouldCaptureAttachBootstrapBaseline: boolean;
+    shouldClearPendingSignature: boolean;
+    shouldRefreshReferenceSnapshots: boolean;
+    shouldSeedWorkspaceSnapshotPushBaseline: boolean;
+    shouldScheduleStartupFullReconcile: boolean;
+    deferredPushSignature: string | null;
+}
+export declare function resolveWorkspacePullRequestPlan({ workspaceSyncPhase, forceCursorNull, currentCursor }: ResolveWorkspacePullRequestPlanArgs): WorkspacePullRequestPlan;
+export declare function resolveWorkspacePullSuccessPlan({ workspaceSyncPhase, forceCursorNull, repairMode, startupFullReconcileRan, pendingSignature, fallbackSignature, lastPushedSignature }: ResolveWorkspacePullSuccessPlanArgs): WorkspacePullSuccessPlan;
+export {};

package/dist/sync/engine/workspaceSyncEnginePullPolicy.js

@@ -0,0 +1,27 @@
+export function resolveWorkspacePullRequestPlan({ workspaceSyncPhase, forceCursorNull, currentCursor }) {
+    const bootstrap = workspaceSyncPhase === 'attach-cloud';
+    return {
+        bootstrap,
+        cursor: bootstrap || forceCursorNull === true ? null : currentCursor,
+        successEventType: bootstrap ? 'bootstrap' : 'pull'
+    };
+}
+export function resolveWorkspacePullSuccessPlan({ workspaceSyncPhase, forceCursorNull, repairMode, startupFullReconcileRan, pendingSignature, fallbackSignature, lastPushedSignature }) {
+    const bootstrap = workspaceSyncPhase === 'attach-cloud';
+    // Normal attach treats the pulled merge as its initial acknowledged baseline.
+    // Repair must preserve the reset baseline so the merged snapshot is pushed in full.
+    const repairingBootstrap = bootstrap && repairMode === true;
+    const nextSignature = pendingSignature || fallbackSignature;
+    const deferredPushSignature = (!bootstrap
+        && nextSignature
+        && nextSignature !== lastPushedSignature) ? nextSignature : null;
+    return {
+        successEventType: bootstrap ? 'bootstrap' : 'pull',
+        shouldCaptureAttachBootstrapBaseline: bootstrap && !repairingBootstrap,
+        shouldClearPendingSignature: bootstrap || deferredPushSignature !== null,
+        shouldRefreshReferenceSnapshots: bootstrap,
+        shouldSeedWorkspaceSnapshotPushBaseline: bootstrap && !repairingBootstrap,
+        shouldScheduleStartupFullReconcile: !forceCursorNull && !bootstrap && !startupFullReconcileRan,
+        deferredPushSignature
+    };
+}

package/dist/sync/engine/workspaceSyncEnginePushCompletion.d.ts

@@ -0,0 +1,20 @@
+import type { WorkspaceSyncChange, WorkspaceSyncDurableTaskRevision, WorkspaceSyncTaskSnapshot } from '../workspaceSyncModel.js';
+export declare const WORKSPACE_SYNC_ENGINE_V2_PUSH_BOUNDARY_VERSION: 1;
+/**
+ * Stable attempt-wide boundary shared by every V2 push batch. Individual
+ * batches retain their own cloud idempotency key as the operation identity.
+ */
+export interface WorkspaceSyncEngineV2PushBoundary {
+    version: typeof WORKSPACE_SYNC_ENGINE_V2_PUSH_BOUNDARY_VERSION;
+    projection: 'v2-push';
+    batchOperationIdentities: readonly string[];
+}
+export declare function createWorkspaceSyncEngineV2PushBoundary(batchOperationIdentities: readonly string[]): WorkspaceSyncEngineV2PushBoundary;
+export declare function parseWorkspaceSyncEngineV2PushBoundary(value: unknown): WorkspaceSyncEngineV2PushBoundary;
+export interface WorkspaceSyncEngineAppliedTaskUpsert {
+    archived: boolean;
+    task: WorkspaceSyncTaskSnapshot;
+    durableRevision?: WorkspaceSyncDurableTaskRevision;
+}
+export declare function workspaceSyncEngineExpectedTaskEchoIds(changes: readonly WorkspaceSyncChange[]): string[];
+export declare function parseWorkspaceSyncEngineAppliedTaskUpserts(value: unknown, expectedTaskIds: readonly string[]): WorkspaceSyncEngineAppliedTaskUpsert[];

package/dist/sync/engine/workspaceSyncEnginePushCompletion.js

@@ -0,0 +1,87 @@
+export const WORKSPACE_SYNC_ENGINE_V2_PUSH_BOUNDARY_VERSION = 1;
+export function createWorkspaceSyncEngineV2PushBoundary(batchOperationIdentities) {
+    if (!Array.isArray(batchOperationIdentities)
+        || batchOperationIdentities.length === 0
+        || batchOperationIdentities.some((identity) => (typeof identity !== 'string'
+            || identity.trim().length === 0
+            || identity !== identity.trim()))
+        || new Set(batchOperationIdentities).size !== batchOperationIdentities.length) {
+        throw new TypeError('A V2 push boundary requires nonempty, unique, trimmed batch operation identities.');
+    }
+    return Object.freeze({
+        version: WORKSPACE_SYNC_ENGINE_V2_PUSH_BOUNDARY_VERSION,
+        projection: 'v2-push',
+        batchOperationIdentities: Object.freeze([...batchOperationIdentities]),
+    });
+}
+export function parseWorkspaceSyncEngineV2PushBoundary(value) {
+    if (!value
+        || typeof value !== 'object'
+        || Array.isArray(value)
+        || value.version
+            !== WORKSPACE_SYNC_ENGINE_V2_PUSH_BOUNDARY_VERSION
+        || value.projection !== 'v2-push'
+        || !Array.isArray(value.batchOperationIdentities)) {
+        throw new TypeError('The V2 push boundary is invalid.');
+    }
+    return createWorkspaceSyncEngineV2PushBoundary(value.batchOperationIdentities);
+}
+export function workspaceSyncEngineExpectedTaskEchoIds(changes) {
+    const taskIds = changes
+        .filter((change) => (change?.op === 'upsert'))
+        .map((change) => String(change.task?.id || '').trim())
+        .filter(Boolean);
+    return Array.from(new Set(taskIds));
+}
+export function parseWorkspaceSyncEngineAppliedTaskUpserts(value, expectedTaskIds) {
+    if (!Array.isArray(expectedTaskIds)
+        || expectedTaskIds.some((taskId) => (typeof taskId !== 'string'
+            || taskId.trim().length === 0
+            || taskId !== taskId.trim()))
+        || new Set(expectedTaskIds).size !== expectedTaskIds.length) {
+        throw new TypeError('The expected V2 push task echo identities are invalid.');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError('The V2 push authoritative echo response is invalid.');
+    }
+    const source = value;
+    if (!Array.isArray(source.appliedTaskUpserts)) {
+        throw new TypeError('The V2 push authoritative echo response is missing appliedTaskUpserts.');
+    }
+    const normalized = source.appliedTaskUpserts
+        .map((entry) => {
+        const candidate = entry && typeof entry === 'object' && !Array.isArray(entry)
+            ? entry
+            : null;
+        if (!candidate || typeof candidate.archived !== 'boolean')
+            return null;
+        const task = candidate.task
+            && typeof candidate.task === 'object'
+            && !Array.isArray(candidate.task)
+            ? candidate.task
+            : null;
+        const taskId = String(task?.id || '').trim();
+        if (!task || !taskId)
+            return null;
+        return {
+            archived: candidate.archived === true,
+            task,
+            ...(candidate.durableRevision
+                && typeof candidate.durableRevision === 'object'
+                && !Array.isArray(candidate.durableRevision)
+                ? {
+                    durableRevision: candidate.durableRevision,
+                }
+                : {}),
+        };
+    })
+        .filter((entry) => Boolean(entry));
+    const actualTaskIds = normalized.map((entry) => String(entry.task.id).trim());
+    if (normalized.length !== source.appliedTaskUpserts.length
+        || actualTaskIds.length !== expectedTaskIds.length
+        || new Set(actualTaskIds).size !== actualTaskIds.length
+        || actualTaskIds.some((taskId, index) => taskId !== expectedTaskIds[index])) {
+        throw new TypeError('The V2 push authoritative task echo contract is incomplete or malformed.');
+    }
+    return normalized;
+}

package/dist/sync/engine/workspaceSyncEngineRecovery.d.ts

@@ -0,0 +1,56 @@
+import type { WorkspaceSyncPhase } from '../workspaceSyncState.js';
+import type { WorkspaceSyncEngineRuntime } from './workspaceSyncEngineRuntime.js';
+import type { WorkspaceSyncEngineLocalServices } from './workspaceSyncEngineLocalServices.js';
+type SyncEventType = 'pull' | 'handshake' | 'bootstrap' | 'apply' | 'push';
+interface CreateSyncRecoveryCoordinatorArgs {
+    currentWorkspaceId: string;
+    workspaceCloudSyncEnabled: boolean;
+    workspaceSyncPhase: WorkspaceSyncPhase;
+    workspaceLastPullAt: string | null;
+    runtime: WorkspaceSyncEngineRuntime;
+    localServices: WorkspaceSyncEngineLocalServices;
+    acquireWorkspaceSyncLease: (workspaceId: string, owner: 'pull' | 'push' | 'repair') => Promise<boolean>;
+    releaseWorkspaceSyncLease: (workspaceId: string) => void;
+    forceClearWorkspaceSyncLease: (workspaceId: string) => void;
+    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;
+        startupFullReconcileCompletedAt: null;
+        lastErrorMessage: null;
+    }) => Promise<unknown>;
+    persistWorkspaceSyncWatermarksSnapshotBestEffort: () => boolean;
+    buildWorkspaceSyncSignature: () => string;
+    pullWorkspaceChangesFromCloud: (options?: {
+        repairMode?: boolean;
+        forceCursorNull?: boolean;
+        forceV3AuthoritativeRepair?: boolean;
+        recoveryBatchId?: string;
+    }) => Promise<boolean>;
+    pushWorkspaceChangesToCloud: (signature: string, options?: {
+        forceAllAiProfiles?: boolean;
+        repairMode?: boolean;
+    }) => Promise<boolean>;
+    cloudAuthConfigured: boolean;
+    runtimeMode: 'local' | 'cloud';
+    isAuthenticated: boolean;
+    checkAuthSession: () => Promise<boolean>;
+    isExecutionAuthorized?: () => boolean;
+    coordinatorGeneration?: number | null;
+}
+export declare function createSyncRecoveryCoordinator({ currentWorkspaceId, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceLastPullAt, runtime, localServices, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease, clearWorkspaceRetry, clearWorkspaceIssue, reportWorkspaceWindowContention, reportSyncEvent, persistWorkspaceSyncPatch, persistWorkspaceSyncWatermarksSnapshotBestEffort, buildWorkspaceSyncSignature, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, cloudAuthConfigured, runtimeMode, isAuthenticated, checkAuthSession, isExecutionAuthorized, coordinatorGeneration, }: CreateSyncRecoveryCoordinatorArgs): {
+    retryWorkspaceCloudSync: () => Promise<boolean>;
+    resetWorkspaceSyncCursorAndPull: () => Promise<void>;
+};
+export {};

package/dist/sync/engine/workspaceSyncEngineRecovery.js

@@ -0,0 +1,288 @@
+import { resolveWorkspaceSyncRepairPhase } from './workspaceSyncEngineLifecyclePolicy.js';
+import { resolveRetrySyncReadiness } from './workspaceSyncEngineControlPlane.js';
+function resetWorkspaceSyncStatePushBaselines(runtime) {
+    runtime.lastPushedTaskIds.current = new Set();
+    runtime.lastPushedWatermarks.current = new Map();
+    runtime.lastPushedTaskChangeKeys.current = new Map();
+    runtime.lastPushedTaskRelationshipChangeKeys.current = new Map();
+    runtime.lastPushedTaxonomyChangeKey.current = '';
+    runtime.lastPushedInitiativeIds.current = new Set();
+    runtime.lastPushedInitiativeWatermarks.current = new Map();
+    runtime.lastPushedWorkstreamIds.current = new Set();
+    runtime.lastPushedWorkstreamWatermarks.current = new Map();
+    runtime.lastPushedAiProfileIds.current = new Set();
+    runtime.lastPushedAiProfileWatermarks.current = new Map();
+    runtime.lastPushedAiProfileChangeKeys.current = new Map();
+    runtime.lastPushedDocumentPaths.current = new Set();
+    runtime.lastPushedDocumentWatermarks.current = new Map();
+    runtime.lastPushedAssetPaths.current = new Set();
+    runtime.lastPushedAssetWatermarks.current = new Map();
+    runtime.baselineResetReason.current = 'repair-reset';
+}
+function resetAllWorkspacePushBaselines(runtime) {
+    resetWorkspaceSyncStatePushBaselines(runtime);
+    runtime.lastPushedDocumentReviewSessionIds.current = new Set();
+    runtime.lastPushedDocumentReviewSessionWatermarks.current = new Map();
+    runtime.lastPushedDocumentReviewCommentIds.current = new Set();
+    runtime.lastPushedDocumentReviewCommentWatermarks.current = new Map();
+    runtime.lastPushedAnnotatedAttachmentSessionIds.current = new Set();
+    runtime.lastPushedAnnotatedAttachmentSessionWatermarks.current = new Map();
+    runtime.lastPushedTaskEventWatermarks.current = new Map();
+}
+async function hashRepairStateSignature(signature) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(signature));
+    return Array.from(new Uint8Array(digest), (value) => value.toString(16).padStart(2, '0')).join('');
+}
+export function createSyncRecoveryCoordinator({ currentWorkspaceId, workspaceCloudSyncEnabled, workspaceSyncPhase, workspaceLastPullAt, runtime, localServices, acquireWorkspaceSyncLease, releaseWorkspaceSyncLease, forceClearWorkspaceSyncLease, clearWorkspaceRetry, clearWorkspaceIssue, reportWorkspaceWindowContention, reportSyncEvent, persistWorkspaceSyncPatch, persistWorkspaceSyncWatermarksSnapshotBestEffort, buildWorkspaceSyncSignature, pullWorkspaceChangesFromCloud, pushWorkspaceChangesToCloud, cloudAuthConfigured, runtimeMode, isAuthenticated, checkAuthSession, isExecutionAuthorized = () => true, coordinatorGeneration = null, }) {
+    const lastBootstrapPhaseRef = runtime.lastBootstrapPhase;
+    const workspaceRepairModeRef = runtime.repairMode;
+    const workspaceForceFullAiProfilePushRef = runtime.forceFullAiProfilePush;
+    const workspaceStartupRepairRanRef = runtime.startupRepairRan;
+    const workspaceStartupFullReconcileRanRef = runtime.startupFullReconcileRan;
+    const workspaceFullReconcileInFlightRef = runtime.fullReconcileInFlight;
+    const workspacePullCursorRef = runtime.pullCursor;
+    const workspaceAttachBootstrapBaselineSignatureRef = runtime.attachBootstrapBaselineSignature;
+    const workspaceCaptureAttachBootstrapBaselineRef = runtime.captureAttachBootstrapBaseline;
+    const workspacePendingSignatureRef = runtime.pendingSignature;
+    const workspacePendingPushReplayRef = runtime.pendingPushReplay;
+    const workspaceLastPushedSignatureRef = runtime.lastPushedSignature;
+    const workspaceBaselineResetReasonRef = runtime.baselineResetReason;
+    const bootstrapPhaseStartedAtRef = runtime.bootstrapPhaseStartedAtMs;
+    const bootstrapLastProgressAtRef = runtime.bootstrapLastProgressAtMs;
+    const retryEventType = workspaceSyncPhase === 'provision-local'
+        ? 'push'
+        : workspaceSyncPhase === 'attach-cloud'
+            ? 'bootstrap'
+            : 'pull';
+    const retryWorkspaceCloudSync = async () => {
+        if (!isExecutionAuthorized())
+            return false;
+        clearWorkspaceRetry();
+        let retryReadiness = resolveRetrySyncReadiness({
+            cloudAuthConfigured,
+            runtimeMode,
+            workspaceCloudSyncEnabled,
+            currentWorkspaceId,
+            isAuthenticated
+        });
+        if (!retryReadiness.allowed && retryReadiness.reason === 'auth-required') {
+            const authed = await checkAuthSession();
+            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') {
+            const signature = buildWorkspaceSyncSignature();
+            if (!signature)
+                return false;
+            return pushWorkspaceChangesToCloud(signature, { forceAllAiProfiles: true });
+        }
+        const pendingPushReplay = workspacePendingPushReplayRef.current;
+        if (workspaceSyncPhase === 'active' && pendingPushReplay) {
+            workspacePendingSignatureRef.current = pendingPushReplay.signature;
+            return pushWorkspaceChangesToCloud(pendingPushReplay.signature, {
+                forceAllAiProfiles: pendingPushReplay.forceAllAiProfiles,
+                repairMode: pendingPushReplay.repairMode
+            });
+        }
+        const pulled = await pullWorkspaceChangesFromCloud();
+        if (workspaceSyncPhase === 'attach-cloud')
+            return pulled;
+        const signature = buildWorkspaceSyncSignature();
+        if (signature) {
+            workspacePendingSignatureRef.current = signature;
+            const pushed = await pushWorkspaceChangesToCloud(signature, {
+                forceAllAiProfiles: workspaceForceFullAiProfilePushRef.current === true
+            });
+            return pulled || pushed;
+        }
+        return pulled;
+    };
+    const resetWorkspaceSyncCursorAndPull = async () => {
+        if (!isExecutionAuthorized())
+            return;
+        const leaseAcquired = await acquireWorkspaceSyncLease(currentWorkspaceId, 'repair');
+        if (!leaseAcquired) {
+            forceClearWorkspaceSyncLease(currentWorkspaceId);
+            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 = resolveWorkspaceSyncRepairPhase({
+            workspaceSyncPhase,
+            lastBootstrapPhase: lastBootstrapPhaseRef.current,
+            workspaceLastPullAt
+        });
+        const shouldResetAllPushBaselines = repairPhase === 'provision-local';
+        // Attach-cloud repair heals a potentially false acknowledgement just like active repair.
+        const shouldResetSyncStatePushBaselines = repairPhase === 'active' || repairPhase === 'attach-cloud';
+        clearWorkspaceRetry();
+        clearWorkspaceIssue();
+        try {
+            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;
+            }
+            let localRecovery = null;
+            if (repairPhase !== 'provision-local') {
+                try {
+                    localRecovery = await localServices.prepareOutboxRecovery(currentWorkspaceId);
+                }
+                catch (error) {
+                    reportSyncEvent(currentWorkspaceId, {
+                        eventType: 'bootstrap',
+                        status: 'error',
+                        errorMessage: String(error?.message || 'Blocked local changes could not enter recovery.'),
+                        details: {
+                            source: 'repair.local-recovery-blocked',
+                            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(runtime);
+                void persistWorkspaceSyncWatermarksSnapshotBestEffort();
+            }
+            workspaceRepairModeRef.current = true;
+            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,
+                pullCursor: null,
+                startupFullReconcileCompletedAt: null,
+                lastErrorMessage: null
+            });
+            if (repairPhase === 'provision-local') {
+                const signature = buildWorkspaceSyncSignature();
+                if (!signature)
+                    return;
+                await pushWorkspaceChangesToCloud(signature, { forceAllAiProfiles: true, repairMode: true });
+                return;
+            }
+            const pulled = await pullWorkspaceChangesFromCloud({
+                repairMode: true,
+                ...(localRecovery?.kind === 'recovery' && localRecovery.needsAuthoritativeRepair ? {
+                    forceV3AuthoritativeRepair: true,
+                    recoveryBatchId: localRecovery.recoveryBatchId,
+                } : {}),
+            });
+            if ((repairPhase !== 'active' && repairPhase !== 'attach-cloud') || !pulled)
+                return;
+            if (shouldResetSyncStatePushBaselines) {
+                resetWorkspaceSyncStatePushBaselines(runtime);
+                void persistWorkspaceSyncWatermarksSnapshotBestEffort();
+            }
+            const signature = buildWorkspaceSyncSignature();
+            if (!signature)
+                return;
+            workspacePendingSignatureRef.current = signature;
+            const pushed = await pushWorkspaceChangesToCloud(signature, { forceAllAiProfiles: true, repairMode: true });
+            if (pushed
+                && coordinatorGeneration !== null
+                && localServices.completeAuthoritativeRepair) {
+                const completion = await localServices.completeAuthoritativeRepair({
+                    workspaceId: currentWorkspaceId,
+                    coordinatorGeneration,
+                    repairId: `repair-${globalThis.crypto.randomUUID()}`,
+                    stateSignatureSha256: await hashRepairStateSignature(signature),
+                });
+                if (!completion.ok || completion.data?.success !== true) {
+                    reportSyncEvent(currentWorkspaceId, {
+                        eventType: 'bootstrap',
+                        status: 'error',
+                        statusCode: completion.status,
+                        errorMessage: String(completion.data?.error
+                            || 'Authoritative repair could not settle coordinator recovery.'),
+                        details: {
+                            source: 'repair.coordinator-recovery-settlement-failed',
+                            phase: workspaceSyncPhase,
+                            code: completion.data?.code || null,
+                        },
+                    });
+                }
+            }
+        }
+        finally {
+            workspaceRepairModeRef.current = false;
+            releaseWorkspaceSyncLease(currentWorkspaceId);
+        }
+    };
+    return {
+        retryWorkspaceCloudSync,
+        resetWorkspaceSyncCursorAndPull
+    };
+}

package/dist/sync/engine/workspaceSyncEngineRemoteServices.d.ts

@@ -0,0 +1,104 @@
+import { handshakeWorkspace, provisionWorkspace, pullWorkspaceChanges, pullWorkspaceCombinedRepair, pullWorkspaceContent, pullWorkspaceInitiativeRepair, pullWorkspaceSyncV3CombinedFeed, pullWorkspaceSyncV3Feed, pullWorkspaceSyncV3TaskCommentAudit, type SyncHttpResult, type WorkspacePushOwnershipPreparation } from '../cloudSyncApi.js';
+import type { WorkspaceSyncChange } from '../workspaceSyncModel.js';
+import type { WorkspaceSyncEngineTransferCompletionGroup } from './workspaceSyncEngineTransferCompletion.js';
+import type { WorkspaceSyncEngineV2PushBoundary } from './workspaceSyncEnginePushCompletion.js';
+export interface WorkspaceSyncEngineRemoteTransferReceipt {
+    /**
+     * Opaque adapter-owned evidence for an applying gateway request.
+     * The sync engine only returns it to an apply-completion-group builder.
+     */
+    readonly token: unknown;
+}
+export declare const WORKSPACE_SYNC_V3_APPLY_NOT_COMMITTED = "WORKSPACE_SYNC_V3_APPLY_NOT_COMMITTED";
+export type WorkspaceSyncEngineV3ApplyDescriptor = {
+    projection: 'initiative' | 'combined';
+    kind: 'delta' | 'repair' | 'fallback-repair';
+    epoch: string;
+    previousCursor: string | null;
+    nextCursor: string | null;
+} | {
+    projection: 'task-comment-audit';
+    kind: 'audit';
+    previousCursor: string | null;
+    nextCursor: string | null;
+};
+export interface WorkspaceSyncEnginePreparedPushInput {
+    workspaceId: string;
+    idempotencyKey: string;
+    pushBoundary: WorkspaceSyncEngineV2PushBoundary;
+    changes: WorkspaceSyncChange[];
+    ownership: WorkspacePushOwnershipPreparation;
+    repairMode?: boolean;
+}
+export type WorkspaceSyncEngineContentPullInput = Parameters<typeof pullWorkspaceContent>[1] & {
+    /**
+     * The V2 cursor whose page owns these content bodies. Server adapters
+     * persist it on every content permit so the whole completion group can
+     * commit against one exact prior boundary.
+     */
+    previousCursor: string | null;
+};
+type RemoteResult<Result> = Awaited<Result> & {
+    transferReceipt?: WorkspaceSyncEngineRemoteTransferReceipt;
+};
+type WithoutCloudResolver<T> = T extends (resolveCloudAuthUrl: (path: string) => string, ...args: infer Args) => infer Result ? (...args: Args) => Promise<RemoteResult<Result>> : never;
+/**
+ * Cloud-runtime operations used by the workspace sync engine.
+ *
+ * The browser adapter preserves the existing authenticated fetch behavior.
+ * A server-owned adapter may implement this port through
+ * WorkspaceSyncTransportGateway. It acknowledges accepted non-applying
+ * handshake, provision, and zero-echo push permits before those operations
+ * settle. Authoritative push echoes, pull/content, and v3 feed permits remain
+ * open and return receipts that are combined with their atomic local apply.
+ */
+export interface WorkspaceSyncEngineRemoteServices {
+    handshakeWorkspace: WithoutCloudResolver<typeof handshakeWorkspace>;
+    provisionWorkspace: WithoutCloudResolver<typeof provisionWorkspace>;
+    pushWorkspaceChanges(input: WorkspaceSyncEnginePreparedPushInput): Promise<SyncHttpResult & {
+        transferReceipt?: WorkspaceSyncEngineRemoteTransferReceipt;
+    }>;
+    pullWorkspaceChanges: WithoutCloudResolver<typeof pullWorkspaceChanges>;
+    pullWorkspaceContent(input: WorkspaceSyncEngineContentPullInput): ReturnType<WithoutCloudResolver<typeof pullWorkspaceContent>>;
+    pullInitiativeFeed: WithoutCloudResolver<typeof pullWorkspaceSyncV3Feed>;
+    pullInitiativeRepair: WithoutCloudResolver<typeof pullWorkspaceInitiativeRepair>;
+    pullCombinedFeed: WithoutCloudResolver<typeof pullWorkspaceSyncV3CombinedFeed>;
+    pullCombinedRepair: WithoutCloudResolver<typeof pullWorkspaceCombinedRepair>;
+    pullTaskCommentAudit: WithoutCloudResolver<typeof pullWorkspaceSyncV3TaskCommentAudit>;
+    /**
+     * Idempotently settles applying receipts that cannot reach an atomic local
+     * apply boundary. Server adapters decide whether the receipt can be
+     * abandoned cleanly or requires durable reconciliation.
+     */
+    abandonTransferReceipts(input: {
+        workspaceId: string;
+        receipts: readonly WorkspaceSyncEngineRemoteTransferReceipt[];
+        errorCode: string;
+    }): void | Promise<void>;
+    /**
+     * Releases accepted push permits whose authoritative response contains no
+     * normalized local task echo and therefore has no local apply boundary.
+     */
+    acknowledgeNonApplyingTransferReceipts(input: {
+        workspaceId: string;
+        receipts: readonly WorkspaceSyncEngineRemoteTransferReceipt[];
+    }): void | Promise<void>;
+    buildV2ApplyCompletionGroup(input: {
+        workspaceId: string;
+        previousCursor: string | null;
+        nextCursor: string | null;
+        receipts: readonly WorkspaceSyncEngineRemoteTransferReceipt[];
+    }): WorkspaceSyncEngineTransferCompletionGroup | undefined;
+    buildV2PushApplyCompletionGroup(input: {
+        workspaceId: string;
+        pushBoundary: WorkspaceSyncEngineV2PushBoundary;
+        receipts: readonly WorkspaceSyncEngineRemoteTransferReceipt[];
+    }): WorkspaceSyncEngineTransferCompletionGroup | undefined;
+    buildV3ApplyCompletionGroup(input: {
+        workspaceId: string;
+        apply: WorkspaceSyncEngineV3ApplyDescriptor;
+        receipts: readonly WorkspaceSyncEngineRemoteTransferReceipt[];
+    }): WorkspaceSyncEngineTransferCompletionGroup | undefined;
+}
+export declare function createBrowserWorkspaceSyncEngineRemoteServices(resolveCloudAuthUrl: (path: string) => string): WorkspaceSyncEngineRemoteServices;
+export {};