@taskforcehq/taskforce 0.3.170 → 0.3.301

package/dist/server/routes/sync.js

@@ -0,0 +1,3143 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash, randomUUID } from 'crypto';
+import { parseJsonBody } from '../routes.js';
+import { normalizeTaskDataRelativePath, ObjectStorageClient } from '../../storage/objectStorageClient.js';
+import { WorkspaceAssetStore } from '../../storage/workspaceAssetStore.js';
+import { resolveSessionCookieAttributesForRequest } from '../auth.js';
+import { decryptDocument, ENCRYPTION_PREFIX } from '../../sync/encryptionService.js';
+import { isAiProfileSurfaceType } from '../../shared/aiProfileSurfaceType.js';
+import { compareWorkspaceMutationOrdering, getTaskMutationTieBreak, getTaskMutationWatermark } from '../../sync/workspaceSyncSurface.js';
+import { applyWorkspaceRepair } from '../../sync/workspaceRepair.js';
+function decodeWorkspaceSyncCursor(raw) {
+    const value = String(raw || '').trim();
+    if (!value)
+        return null;
+    try {
+        const json = Buffer.from(value, 'base64url').toString('utf8');
+        const parsed = JSON.parse(json);
+        const u = String(parsed?.u || '').trim();
+        const id = String(parsed?.id || '').trim();
+        if (!u || !id)
+            return null;
+        if (!Number.isFinite(Date.parse(u)))
+            return null;
+        return { u, id };
+    }
+    catch {
+        return null;
+    }
+}
+function encodeWorkspaceSyncCursor(cursor) {
+    if (!cursor)
+        return null;
+    return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');
+}
+function createSyncRouteError(message, details, options) {
+    const error = new Error(message);
+    error.code = options?.code || 'SYNC_APPLY_FAILED';
+    error.statusCode = options?.statusCode || 500;
+    error.details = details;
+    return error;
+}
+function normalizeIncomingAiProfileSurfaceType(value, context) {
+    if (value === undefined || value === null)
+        return null;
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        return null;
+    if (!isAiProfileSurfaceType(normalized)) {
+        throw createSyncRouteError(`Invalid ai profile surfaceType "${normalized}"`, {
+            ...context,
+            surfaceType: normalized
+        }, { code: 'AI_PROFILE_SURFACE_TYPE_INVALID', statusCode: 400 });
+    }
+    return normalized;
+}
+export function registerSyncRoutes(deps) {
+    const { addRoute, core, context, auditAuthAction, resolveErrorStatusCode, requestWorkspaceId, resolveRequestAccess, isReservedWorkspaceId, createSessionTokenCookie } = deps;
+    const readPushIdempotency = (workspaceId, key) => {
+        return core.readPushIdempotency(workspaceId, key);
+    };
+    const workspaceAssetStore = typeof core.getDatabaseAdapter === 'function' && typeof core.getTenantId === 'function'
+        ? new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId())
+        : null;
+    const resolveEffectiveObjectStorageConfig = () => {
+        const base = context.objectStorage || { provider: 'local' };
+        return base;
+    };
+    const getObjectStorageClient = () => {
+        const resolved = resolveEffectiveObjectStorageConfig();
+        return resolved.provider === 'r2' ? new ObjectStorageClient(resolved) : null;
+    };
+    const writePushIdempotency = (workspaceId, key, payload) => {
+        core.writePushIdempotency(workspaceId, key, payload);
+    };
+    const recordSyncDiagnostic = (workspaceId, eventType, errorMessage, details) => {
+        try {
+            core.recordSyncEvent(workspaceId, {
+                eventType,
+                status: 'error',
+                errorMessage,
+                requestMs: 0,
+                details
+            });
+        }
+        catch {
+            // diagnostics must never throw
+        }
+        if (details && Object.keys(details).length > 0) {
+            // eslint-disable-next-line no-console
+            console.warn('[Taskforce Sync Diagnostic]', { workspaceId, eventType, errorMessage, ...details });
+        }
+    };
+    const validateTaskActorAssignments = (workspaceId, tasks, archived) => {
+        const entries = [...tasks, ...archived];
+        if (entries.length === 0)
+            return;
+        for (const task of entries) {
+            const assignee = String(task.assignee || '').trim();
+            if (!assignee || assignee === 'unassigned')
+                continue;
+            const actor = core.resolveWorkspaceActor(workspaceId, assignee);
+            if (actor && actor.meta?.unresolved !== true)
+                continue;
+            const unresolvedKind = actor?.kind === 'ai' ? 'ai' : 'human';
+            if (unresolvedKind === 'human')
+                continue;
+            throw createSyncRouteError(`Task ${String(task.id || '').trim() || '(unknown task)'} references unresolved assignee ${assignee}.`, {
+                source: 'apply.assigneeValidation',
+                workspaceId,
+                taskId: String(task.id || '').trim() || null,
+                assignee
+            }, { code: 'TASK_ACTOR_RESOLUTION_FAILED', statusCode: 400 });
+        }
+    };
+    const assertSyncedAiProfilesPersisted = (workspaceId, incomingAiProfiles) => {
+        if (incomingAiProfiles.size === 0)
+            return;
+        const persistedIds = new Set(core.listAiProfiles(workspaceId)
+            .map((profile) => String(profile.id || '').trim())
+            .filter(Boolean));
+        for (const profile of incomingAiProfiles.values()) {
+            if (persistedIds.has(profile.id))
+                continue;
+            throw createSyncRouteError(`AI profile ${profile.id} was not persisted during sync apply.`, {
+                source: 'apply.aiProfileIntegrityCheck',
+                workspaceId,
+                profileId: profile.id,
+                expectedAiProfileCount: incomingAiProfiles.size,
+                persistedAiProfileCount: persistedIds.size
+            }, { code: 'AI_PROFILE_SYNC_APPLY_FAILED', statusCode: 500 });
+        }
+    };
+    const normalizeWorkspaceMemberSyncSnapshot = (workspaceId, raw) => {
+        const userId = String(raw?.userId || '').trim();
+        const email = String(raw?.email || '').trim().toLowerCase();
+        if (!userId || !email)
+            return null;
+        return {
+            userId,
+            workspaceId: String(raw?.workspaceId || workspaceId).trim() || workspaceId,
+            email,
+            displayName: typeof raw?.displayName === 'string' ? raw.displayName.trim() || null : null,
+            role: String(raw?.role || 'member').trim() || 'member',
+            permissionMode: String(raw?.permissionMode || 'read-write').trim() || 'read-write',
+            betaAccess: raw?.betaAccess !== false,
+            status: String(raw?.status || 'active').trim() || 'active',
+            disabled: raw?.disabled === true,
+            createdAt: typeof raw?.createdAt === 'string' ? raw.createdAt.trim() || null : null,
+            updatedAt: typeof raw?.updatedAt === 'string' ? raw.updatedAt.trim() || null : null,
+            emailVerifiedAt: typeof raw?.emailVerifiedAt === 'string' ? raw.emailVerifiedAt.trim() || null : null
+        };
+    };
+    const workspaceDocumentSnapshotCache = new Map();
+    const workspaceTaxonomySyncMeta = new Map();
+    const isMarkdownPath = (relativePath) => {
+        const lower = relativePath.toLowerCase();
+        return lower.endsWith('.md') || lower.endsWith('.markdown');
+    };
+    const normalizeWorkspaceSyncDocumentPath = (rawPath) => {
+        const value = String(rawPath || '').trim().replace(/\\/g, '/');
+        if (!value || value.includes('\0'))
+            return null;
+        if (value.startsWith('/'))
+            return null;
+        const normalized = path.posix.normalize(value);
+        if (!normalized || normalized.startsWith('../') || normalized.includes('/../') || normalized === '..')
+            return null;
+        if (!isMarkdownPath(normalized))
+            return null;
+        if (/^workspaces\/[^/]+\/assets\/documents\//.test(normalized))
+            return normalized;
+        if (normalized.startsWith('docs/'))
+            return normalized;
+        return null;
+    };
+    const resolveCanonicalAssetSyncLinkState = (asset, workspaceId) => {
+        if (!workspaceAssetStore) {
+            return {
+                primaryLink: null,
+                effectiveUpdatedAt: String(asset.updatedAt || asset.createdAt || '').trim() || new Date().toISOString()
+            };
+        }
+        const links = workspaceAssetStore.listLinksForAsset(asset.assetId, workspaceId, { includeDeleted: true });
+        const activeLinks = links.filter((entry) => !entry.deletedAt);
+        const primaryLink = activeLinks[0] || null;
+        let effectiveUpdatedAt = String(asset.updatedAt || asset.createdAt || '').trim() || new Date().toISOString();
+        for (const link of links) {
+            const linkUpdatedAt = String(link.updatedAt || link.createdAt || '').trim();
+            if (linkUpdatedAt && linkUpdatedAt > effectiveUpdatedAt)
+                effectiveUpdatedAt = linkUpdatedAt;
+        }
+        return { primaryLink, effectiveUpdatedAt };
+    };
+    const getCanonicalSyncDocumentMetadata = (relativePath, workspaceId) => {
+        if (!workspaceAssetStore)
+            return {};
+        const asset = workspaceAssetStore.getByStorageKey(relativePath, workspaceId);
+        if (!asset || asset.kind !== 'document')
+            return {};
+        const { primaryLink } = resolveCanonicalAssetSyncLinkState(asset, workspaceId);
+        return {
+            assetId: asset.assetId,
+            documentId: asset.documentId,
+            referenceNumber: asset.referenceNumber,
+            version: asset.version,
+            taskId: primaryLink?.taskId || null,
+            logicalName: asset.logicalName || null,
+            caption: primaryLink?.displayName || null,
+            originalFilename: asset.originalFilename || path.basename(relativePath),
+            linkRole: primaryLink?.role === 'reference' ? 'reference' : 'attachment'
+        };
+    };
+    const hasDocumentSyncMetadataDrift = (workspaceId, doc, options) => {
+        if (!workspaceAssetStore)
+            return false;
+        const existingAsset = workspaceAssetStore.getByStorageKey(doc.path, workspaceId);
+        if (!existingAsset || existingAsset.kind !== 'document')
+            return false;
+        const { primaryLink } = resolveCanonicalAssetSyncLinkState(existingAsset, workspaceId);
+        const normalizedIncomingReference = Number.isFinite(Number(doc.referenceNumber))
+            ? Math.max(1, Math.floor(Number(doc.referenceNumber)))
+            : null;
+        const normalizedIncomingVersion = Number.isFinite(Number(doc.version))
+            ? Math.max(1, Math.floor(Number(doc.version)))
+            : null;
+        const normalizedIncomingDocumentId = typeof doc.documentId === 'string' && doc.documentId.trim().length > 0
+            ? doc.documentId.trim()
+            : null;
+        const normalizedIncomingLogicalName = typeof doc.logicalName === 'string' && doc.logicalName.trim().length > 0
+            ? doc.logicalName.trim()
+            : null;
+        const normalizedIncomingCaption = typeof doc.caption === 'string' && doc.caption.trim().length > 0
+            ? doc.caption.trim()
+            : null;
+        const normalizedIncomingFilename = typeof doc.originalFilename === 'string' && doc.originalFilename.trim().length > 0
+            ? doc.originalFilename.trim()
+            : null;
+        const normalizedIncomingTaskId = typeof doc.taskId === 'string' && doc.taskId.trim().length > 0
+            ? doc.taskId.trim()
+            : null;
+        const normalizedIncomingLinkRole = doc.linkRole === 'reference' ? 'reference' : 'attachment';
+        const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
+        if (!allowReferenceNumberReassignment
+            && existingAsset.referenceNumber
+            && normalizedIncomingReference
+            && existingAsset.referenceNumber !== normalizedIncomingReference) {
+            recordSyncDiagnostic(workspaceId, 'apply', 'Detected document reference number mismatch during normal sync.', {
+                source: 'documents.referenceNumber.mismatch',
+                path: doc.path,
+                assetId: existingAsset.assetId,
+                existingReferenceNumber: existingAsset.referenceNumber,
+                incomingReferenceNumber: normalizedIncomingReference
+            });
+        }
+        return (allowReferenceNumberReassignment && existingAsset.referenceNumber !== normalizedIncomingReference)
+            || existingAsset.version !== normalizedIncomingVersion
+            || (existingAsset.documentId || null) !== normalizedIncomingDocumentId
+            || (existingAsset.logicalName || null) !== normalizedIncomingLogicalName
+            || (existingAsset.originalFilename || null) !== normalizedIncomingFilename
+            || (primaryLink?.taskId || null) !== normalizedIncomingTaskId
+            || (primaryLink?.displayName || null) !== normalizedIncomingCaption
+            || ((primaryLink?.role === 'reference' ? 'reference' : 'attachment')) !== normalizedIncomingLinkRole;
+    };
+    const hasBinaryAssetSyncMetadataDrift = (workspaceId, asset, options) => {
+        if (!workspaceAssetStore)
+            return false;
+        const existingAsset = workspaceAssetStore.getByStorageKey(asset.path, workspaceId);
+        if (!existingAsset || (existingAsset.kind !== 'image' && existingAsset.kind !== 'file'))
+            return false;
+        const { primaryLink } = resolveCanonicalAssetSyncLinkState(existingAsset, workspaceId);
+        const normalizedIncomingReference = Number.isFinite(Number(asset.referenceNumber))
+            ? Math.max(1, Math.floor(Number(asset.referenceNumber)))
+            : null;
+        const normalizedIncomingLogicalName = typeof asset.logicalName === 'string' && asset.logicalName.trim().length > 0
+            ? asset.logicalName.trim()
+            : null;
+        const normalizedIncomingCaption = typeof asset.caption === 'string' && asset.caption.trim().length > 0
+            ? asset.caption.trim()
+            : null;
+        const normalizedIncomingFilename = typeof asset.originalFilename === 'string' && asset.originalFilename.trim().length > 0
+            ? asset.originalFilename.trim()
+            : null;
+        const normalizedIncomingTaskId = typeof asset.taskId === 'string' && asset.taskId.trim().length > 0
+            ? asset.taskId.trim()
+            : null;
+        const normalizedIncomingLinkRole = asset.linkRole === 'reference'
+            ? 'reference'
+            : asset.kind === 'image'
+                ? 'image'
+                : 'attachment';
+        const allowReferenceNumberReassignment = options?.allowReferenceNumberReassignment === true;
+        if (!allowReferenceNumberReassignment
+            && existingAsset.referenceNumber
+            && normalizedIncomingReference
+            && existingAsset.referenceNumber !== normalizedIncomingReference) {
+            recordSyncDiagnostic(workspaceId, 'apply', 'Detected asset reference number mismatch during normal sync.', {
+                source: 'assets.referenceNumber.mismatch',
+                path: asset.path,
+                assetId: existingAsset.assetId,
+                existingReferenceNumber: existingAsset.referenceNumber,
+                incomingReferenceNumber: normalizedIncomingReference
+            });
+        }
+        return (allowReferenceNumberReassignment && existingAsset.referenceNumber !== normalizedIncomingReference)
+            || (existingAsset.logicalName || null) !== normalizedIncomingLogicalName
+            || (existingAsset.originalFilename || null) !== normalizedIncomingFilename
+            || (primaryLink?.taskId || null) !== normalizedIncomingTaskId
+            || (primaryLink?.displayName || null) !== normalizedIncomingCaption
+            || ((primaryLink?.role === 'reference'
+                ? 'reference'
+                : existingAsset.kind === 'image'
+                    ? 'image'
+                    : 'attachment')) !== normalizedIncomingLinkRole;
+    };
+    const reconcileWorkspaceSyncLinks = (input) => {
+        if (!workspaceAssetStore)
+            return;
+        const workspaceId = String(input.workspaceId || '').trim() || 'default';
+        const assetId = String(input.assetId || '').trim();
+        if (!assetId)
+            return;
+        const desiredTaskId = String(input.taskId || '').trim();
+        const desiredRole = input.role === 'reference'
+            ? 'reference'
+            : input.role === 'image'
+                ? 'image'
+                : 'attachment';
+        const linkUpdatedAt = String(input.updatedAt || '').trim() || new Date().toISOString();
+        const existingLinks = workspaceAssetStore.listLinksForAsset(assetId, workspaceId, { includeDeleted: true });
+        if (desiredTaskId) {
+            workspaceAssetStore.upsertLink({
+                workspaceId,
+                assetId,
+                taskId: desiredTaskId,
+                role: desiredRole,
+                displayName: typeof input.displayName === 'string' && input.displayName.trim().length > 0 ? input.displayName.trim() : null,
+                updatedAt: linkUpdatedAt,
+                deletedAt: null
+            });
+        }
+        // Only clean up stale links when we have an explicit incoming taskId. If the incoming
+        // asset-upsert carries no taskId, there is no authoritative association to enforce, so
+        // preserve all existing links rather than wiping them.
+        if (desiredTaskId) {
+            for (const link of existingLinks) {
+                if (link.taskId === desiredTaskId && link.role === desiredRole)
+                    continue;
+                if (link.deletedAt)
+                    continue;
+                workspaceAssetStore.deleteLink({
+                    workspaceId,
+                    assetId,
+                    taskId: link.taskId,
+                    role: link.role
+                });
+            }
+        }
+    };
+    const listWorkspaceSyncDocumentDeletesSnapshot = (workspaceId = 'default') => {
+        if (!workspaceAssetStore)
+            return [];
+        const entries = workspaceAssetStore.listAllByWorkspace(workspaceId, {
+            includeDeleted: true,
+            kind: 'document'
+        })
+            .filter((asset) => typeof asset.deletedAt === 'string' && asset.deletedAt.trim().length > 0)
+            .map((asset) => {
+            const normalizedPath = normalizeWorkspaceSyncDocumentPath(asset.storageKey);
+            if (!normalizedPath)
+                return null;
+            return {
+                path: normalizedPath,
+                deletedAt: String(asset.deletedAt || '').trim(),
+                assetId: asset.assetId
+            };
+        });
+        return entries.filter((entry) => Boolean(entry && entry.path && entry.deletedAt));
+    };
+    const listWorkspaceSyncDocumentReviewSessionsSnapshot = (workspaceId = 'default') => {
+        return core.listDocumentReviewSessionsForSync({ workspaceId, includeDeleted: true })
+            .map((session) => ({
+            id: session.id,
+            assetId: session.assetId,
+            documentId: session.documentId,
+            documentVersion: session.documentVersion,
+            title: session.title,
+            status: session.status,
+            comments: session.comments,
+            createdByActorId: session.createdByActorId,
+            updatedByActorId: session.updatedByActorId,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+            deletedAt: session.deletedAt,
+        }))
+            .filter((session) => session.id.length > 0 && session.assetId.length > 0);
+    };
+    const listWorkspaceSyncDocumentReviewCommentsSnapshot = (workspaceId = 'default') => {
+        return core.listDocumentReviewCommentsForSync({ workspaceId, includeDeleted: true })
+            .map((comment) => ({
+            id: comment.id,
+            sessionId: comment.sessionId,
+            body: comment.body,
+            anchor: comment.anchor,
+            order: comment.order,
+            authorActorId: comment.authorActorId,
+            createdAt: comment.createdAt,
+            updatedAt: comment.updatedAt,
+            deletedAt: comment.deletedAt,
+        }))
+            .filter((comment) => comment.id.length > 0 && comment.sessionId.length > 0);
+    };
+    const listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot = (workspaceId = 'default') => {
+        return core.listAnnotatedAttachmentSessionsForSync({ workspaceId, includeDeleted: true })
+            .map((session) => ({
+            id: session.id,
+            workspaceId: session.workspaceId,
+            taskId: session.taskId,
+            baseImageAssetId: session.baseImageAssetId,
+            title: session.title,
+            globalInstruction: session.globalInstruction,
+            annotations: session.annotations,
+            createdByActorId: session.createdByActorId,
+            updatedByActorId: session.updatedByActorId,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+            deletedAt: session.deletedAt,
+        }))
+            .filter((session) => (session.id.length > 0
+            && session.workspaceId.length > 0
+            && session.baseImageAssetId.length > 0));
+    };
+    const listWorkspaceSyncDocumentsSnapshot = async (basePath, workspaceId = 'default') => {
+        const root = path.resolve(basePath);
+        const objectStorageClient = getObjectStorageClient();
+        const candidatePaths = new Set();
+        const docsRoot = path.join(root, 'docs');
+        const collectMarkdownPaths = (directory) => {
+            if (!fs.existsSync(directory))
+                return;
+            const entries = fs.readdirSync(directory, { withFileTypes: true });
+            for (const entry of entries) {
+                const absolutePath = path.join(directory, entry.name);
+                if (entry.isDirectory()) {
+                    collectMarkdownPaths(absolutePath);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                const relativeFromRoot = path.relative(root, absolutePath).replace(/\\/g, '/');
+                const normalized = normalizeWorkspaceSyncDocumentPath(relativeFromRoot);
+                if (normalized)
+                    candidatePaths.add(normalized);
+            }
+        };
+        collectMarkdownPaths(docsRoot);
+        if (workspaceAssetStore) {
+            const canonicalAssets = workspaceAssetStore.listAllByWorkspace(workspaceId, {
+                includeDeleted: false,
+                kind: 'document'
+            });
+            for (const asset of canonicalAssets) {
+                const normalized = normalizeWorkspaceSyncDocumentPath(asset.storageKey);
+                if (normalized)
+                    candidatePaths.add(normalized);
+            }
+        }
+        const uniquePaths = Array.from(candidatePaths).sort((a, b) => a.localeCompare(b));
+        const workspaceCache = workspaceDocumentSnapshotCache.get(workspaceId) || new Map();
+        workspaceDocumentSnapshotCache.set(workspaceId, workspaceCache);
+        const remainingPaths = new Set(uniquePaths);
+        const docs = [];
+        for (const relativePath of uniquePaths) {
+            try {
+                const canonicalAsset = workspaceAssetStore?.getByStorageKey(relativePath, workspaceId);
+                let stat = null;
+                let content = null;
+                let updatedAt = '';
+                if (canonicalAsset?.kind === 'document') {
+                    updatedAt = resolveCanonicalAssetSyncLinkState(canonicalAsset, workspaceId).effectiveUpdatedAt;
+                    if (canonicalAsset.storageProvider === 'r2' && objectStorageClient) {
+                        const object = await objectStorageClient.getObject(relativePath);
+                        if (!object?.body)
+                            continue;
+                        content = object.body.toString('utf8');
+                    }
+                    else {
+                        const absPath = path.resolve(path.join(root, relativePath));
+                        if (absPath !== root && !absPath.startsWith(`${root}${path.sep}`))
+                            continue;
+                        if (!fs.existsSync(absPath))
+                            continue;
+                        stat = fs.statSync(absPath);
+                        if (!stat.isFile())
+                            continue;
+                        content = fs.readFileSync(absPath, 'utf8');
+                    }
+                }
+                else {
+                    const absPath = path.resolve(path.join(basePath, relativePath));
+                    const safeRoot = path.resolve(basePath);
+                    if (absPath !== safeRoot && !absPath.startsWith(`${safeRoot}${path.sep}`))
+                        continue;
+                    stat = fs.statSync(absPath);
+                    if (!stat.isFile())
+                        continue;
+                    content = fs.readFileSync(absPath, 'utf8');
+                }
+                if (content == null)
+                    continue;
+                const cached = workspaceCache.get(relativePath);
+                if (cached
+                    && cached.size === Buffer.byteLength(content, 'utf8')
+                    && (canonicalAsset
+                        ? cached.updatedAt === updatedAt
+                        : (stat != null && cached.mtimeMs === stat.mtimeMs && cached.ctimeMs === stat.ctimeMs))) {
+                    docs.push({
+                        path: relativePath,
+                        updatedAt: cached.updatedAt,
+                        content: cached.content,
+                        ...getCanonicalSyncDocumentMetadata(relativePath, workspaceId)
+                    });
+                    continue;
+                }
+                if (!canonicalAsset) {
+                    const contentHash = createHash('sha256').update(content).digest('hex');
+                    const existing = core.getDocumentWatermark(workspaceId, relativePath);
+                    if (existing && existing.contentHash === contentHash) {
+                        updatedAt = existing.updatedAt;
+                    }
+                    else {
+                        updatedAt = stat && Number.isFinite(stat.mtimeMs)
+                            ? new Date(stat.mtimeMs).toISOString()
+                            : new Date().toISOString();
+                        try {
+                            core.upsertDocumentWatermark(workspaceId, relativePath, contentHash, updatedAt);
+                        }
+                        catch (error) {
+                            recordSyncDiagnostic(workspaceId, 'pull', 'Failed to persist document watermark during snapshot.', {
+                                source: 'documents.snapshot.upsertWatermark',
+                                path: relativePath,
+                                error: String(error?.message || error || '')
+                            });
+                        }
+                    }
+                }
+                docs.push({
+                    path: relativePath,
+                    updatedAt,
+                    content,
+                    ...getCanonicalSyncDocumentMetadata(relativePath, workspaceId)
+                });
+                workspaceCache.set(relativePath, {
+                    path: relativePath,
+                    mtimeMs: stat?.mtimeMs ?? 0,
+                    ctimeMs: stat?.ctimeMs ?? 0,
+                    size: Buffer.byteLength(content, 'utf8'),
+                    updatedAt,
+                    content
+                });
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'pull', 'Failed to read sync document snapshot entry.', {
+                    source: 'documents.snapshot.readEntry',
+                    path: relativePath,
+                    error: String(error?.message || error || '')
+                });
+            }
+        }
+        for (const cachedPath of Array.from(workspaceCache.keys())) {
+            if (!remainingPaths.has(cachedPath))
+                workspaceCache.delete(cachedPath);
+        }
+        return docs;
+    };
+    const listWorkspaceSyncBinaryAssetsSnapshot = async (basePath, workspaceId = 'default') => {
+        if (!workspaceAssetStore)
+            return [];
+        const root = path.resolve(basePath);
+        const objectStorageClient = getObjectStorageClient();
+        const assets = workspaceAssetStore.listAllByWorkspace(workspaceId, {
+            includeDeleted: false
+        });
+        const snapshots = [];
+        for (const asset of assets) {
+            if (asset.kind !== 'image' && asset.kind !== 'file')
+                continue;
+            // External references are not syncable binary payloads.
+            if (asset.storageProvider === 'external')
+                continue;
+            const storageKey = String(asset.storageKey || '').trim();
+            if (!storageKey)
+                continue;
+            // Skip legacy task-data assets — they cannot be received on the other end
+            if (!normalizeTaskDataRelativePath(storageKey))
+                continue;
+            try {
+                let buffer = null;
+                if (asset.storageProvider === 'r2' && objectStorageClient) {
+                    const object = await objectStorageClient.getObject(storageKey);
+                    buffer = object?.body || null;
+                }
+                else {
+                    const absolutePath = path.resolve(root, storageKey);
+                    if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`))
+                        continue;
+                    if (!fs.existsSync(absolutePath)) {
+                        recordSyncDiagnostic(workspaceId, 'push', 'Asset registered in DB but file missing from disk — skipped from sync payload.', {
+                            source: 'assets.snapshot.missingFile',
+                            assetId: asset.assetId,
+                            path: storageKey
+                        });
+                        continue;
+                    }
+                    buffer = fs.readFileSync(absolutePath);
+                }
+                if (!buffer) {
+                    recordSyncDiagnostic(workspaceId, 'push', 'Asset registered in DB but content could not be read — skipped from sync payload.', {
+                        source: 'assets.snapshot.emptyBuffer',
+                        assetId: asset.assetId,
+                        path: storageKey,
+                        storageProvider: asset.storageProvider
+                    });
+                    continue;
+                }
+                const { primaryLink, effectiveUpdatedAt } = resolveCanonicalAssetSyncLinkState(asset, workspaceId);
+                snapshots.push({
+                    path: storageKey,
+                    updatedAt: effectiveUpdatedAt,
+                    contentBase64: buffer.toString('base64'),
+                    assetId: asset.assetId,
+                    kind: asset.kind,
+                    mimeType: asset.mimeType || 'application/octet-stream',
+                    referenceNumber: asset.referenceNumber,
+                    taskId: primaryLink?.taskId || null,
+                    logicalName: asset.logicalName || null,
+                    caption: primaryLink?.displayName || null,
+                    originalFilename: asset.originalFilename || path.basename(storageKey),
+                    linkRole: primaryLink?.role || (asset.kind === 'image' ? 'image' : 'attachment')
+                });
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'pull', 'Failed to read binary asset snapshot entry.', {
+                    source: 'assets.snapshot.readEntry',
+                    path: storageKey,
+                    error: String(error?.message || error || '')
+                });
+            }
+        }
+        return snapshots;
+    };
+    const listWorkspaceSyncBinaryAssetDeletesSnapshot = (workspaceId = 'default') => {
+        if (!workspaceAssetStore)
+            return [];
+        const entries = workspaceAssetStore.listAllByWorkspace(workspaceId, {
+            includeDeleted: true
+        })
+            .filter((asset) => ((asset.kind === 'image' || asset.kind === 'file')
+            && asset.storageProvider !== 'external'
+            && typeof asset.deletedAt === 'string'
+            && asset.deletedAt.trim().length > 0))
+            .map((asset) => {
+            const normalizedPath = normalizeTaskDataRelativePath(asset.storageKey);
+            if (!normalizedPath)
+                return null;
+            return {
+                path: normalizedPath,
+                deletedAt: String(asset.deletedAt || '').trim(),
+                assetId: asset.assetId
+            };
+        });
+        return entries.filter((entry) => Boolean(entry && entry.path && entry.deletedAt));
+    };
+    const writeWorkspaceSyncDocument = async (basePath, doc, workspaceId = 'default', options) => {
+        const normalizedPath = normalizeWorkspaceSyncDocumentPath(doc.path);
+        if (!normalizedPath)
+            return;
+        const root = path.resolve(basePath);
+        const targetPath = path.resolve(root, normalizedPath);
+        if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`))
+            return;
+        const objectStorageClient = getObjectStorageClient();
+        const content = String(doc.content || '');
+        if (objectStorageClient) {
+            try {
+                await objectStorageClient.putObject(normalizedPath, Buffer.from(content, 'utf8'), 'text/markdown');
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to write document to object storage.', {
+                    source: 'documents.write.putObject',
+                    path: normalizedPath,
+                    error: String(error?.message || error || '')
+                });
+                return;
+            }
+        }
+        else {
+            fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+            fs.writeFileSync(targetPath, content, 'utf8');
+        }
+        const updatedAt = String(doc.updatedAt || '').trim();
+        const watermarkMs = Date.parse(updatedAt);
+        if (!objectStorageClient && Number.isFinite(watermarkMs) && watermarkMs > 0) {
+            const when = new Date(watermarkMs);
+            fs.utimesSync(targetPath, when, when);
+        }
+        // Persist content hash + timestamp to SQLite so the snapshot function uses a
+        // stable watermark instead of relying on non-deterministic filesystem mtime.
+        try {
+            const contentHash = createHash('sha256').update(content).digest('hex');
+            core.upsertDocumentWatermark(workspaceId, normalizedPath, contentHash, updatedAt || new Date().toISOString());
+            if (workspaceAssetStore) {
+                const existing = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+                const effectiveUpdatedAt = updatedAt || new Date().toISOString();
+                const originalFilename = String(doc.originalFilename || existing?.originalFilename || path.basename(normalizedPath) || 'document.md').trim() || 'document.md';
+                const asset = workspaceAssetStore.upsertAsset({
+                    assetId: String(doc.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
+                    workspaceId,
+                    kind: 'document',
+                    logicalName: typeof doc.logicalName === 'string' && doc.logicalName.trim().length > 0
+                        ? doc.logicalName.trim()
+                        : existing?.logicalName || null,
+                    originalFilename,
+                    mimeType: existing?.mimeType || 'text/markdown',
+                    storageProvider: objectStorageClient ? 'r2' : 'local',
+                    storageKey: normalizedPath,
+                    contentSha256: contentHash,
+                    sizeBytes: Buffer.byteLength(content, 'utf8'),
+                    documentId: String(doc.documentId || existing?.documentId || `doc-${randomUUID().replace(/-/g, '')}`),
+                    referenceNumber: Number.isFinite(Number(doc.referenceNumber))
+                        ? Math.max(1, Math.floor(Number(doc.referenceNumber)))
+                        : existing?.referenceNumber || null,
+                    version: Number.isFinite(Number(doc.version))
+                        ? Math.max(1, Math.floor(Number(doc.version)))
+                        : Math.max(1, Number(existing?.version || 0) + 1),
+                    isLatest: true,
+                    scanStatus: existing?.scanStatus || 'clean',
+                    scanEngine: existing?.scanEngine || null,
+                    scanDetails: existing?.scanDetails || null,
+                    createdByUserId: existing?.createdByUserId || null,
+                    createdAt: existing?.createdAt || effectiveUpdatedAt,
+                    updatedAt: effectiveUpdatedAt,
+                    deletedAt: null,
+                    purgeAfter: null,
+                    allowReferenceNumberReassignment: options?.allowReferenceNumberReassignment === true
+                });
+                const taskId = String(doc.taskId || '').trim();
+                reconcileWorkspaceSyncLinks({
+                    workspaceId,
+                    assetId: asset.assetId,
+                    taskId,
+                    displayName: typeof doc.caption === 'string' && doc.caption.trim().length > 0 ? doc.caption.trim() : null,
+                    role: doc.linkRole === 'reference' ? 'reference' : 'attachment',
+                    updatedAt: effectiveUpdatedAt
+                });
+            }
+        }
+        catch (error) {
+            recordSyncDiagnostic(workspaceId, 'apply', 'Failed to persist document watermark after write.', {
+                source: 'documents.write.upsertWatermark',
+                path: normalizedPath,
+                error: String(error?.message || error || '')
+            });
+        }
+        workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
+    };
+    const writeWorkspaceSyncBinaryAsset = async (basePath, asset, workspaceId = 'default', options) => {
+        const normalizedPath = normalizeTaskDataRelativePath(asset.path);
+        if (!normalizedPath)
+            return;
+        const root = path.resolve(basePath);
+        const targetPath = path.resolve(root, normalizedPath);
+        if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`))
+            return;
+        const objectStorageClient = getObjectStorageClient();
+        const buffer = Buffer.from(String(asset.contentBase64 || ''), 'base64');
+        if (objectStorageClient) {
+            try {
+                await objectStorageClient.putObject(normalizedPath, buffer, String(asset.mimeType || 'application/octet-stream').trim() || 'application/octet-stream');
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'apply', 'Failed to write binary asset to object storage.', {
+                    source: 'assets.write.putObject',
+                    path: normalizedPath,
+                    error: String(error?.message || error || '')
+                });
+                return;
+            }
+        }
+        else {
+            fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+            fs.writeFileSync(targetPath, buffer);
+        }
+        const updatedAt = String(asset.updatedAt || '').trim();
+        const watermarkMs = Date.parse(updatedAt);
+        if (!objectStorageClient && Number.isFinite(watermarkMs) && watermarkMs > 0) {
+            const when = new Date(watermarkMs);
+            fs.utimesSync(targetPath, when, when);
+        }
+        if (!workspaceAssetStore)
+            return;
+        try {
+            const existing = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+            const effectiveUpdatedAt = updatedAt || new Date().toISOString();
+            const assetRecord = workspaceAssetStore.upsertAsset({
+                assetId: String(asset.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`),
+                workspaceId,
+                kind: asset.kind === 'image' ? 'image' : 'file',
+                logicalName: typeof asset.logicalName === 'string' && asset.logicalName.trim().length > 0
+                    ? asset.logicalName.trim()
+                    : existing?.logicalName || null,
+                originalFilename: String(asset.originalFilename || existing?.originalFilename || path.basename(normalizedPath) || 'asset').trim() || 'asset',
+                mimeType: String(asset.mimeType || existing?.mimeType || 'application/octet-stream').trim() || 'application/octet-stream',
+                storageProvider: objectStorageClient ? 'r2' : 'local',
+                storageKey: normalizedPath,
+                contentSha256: createHash('sha256').update(buffer).digest('hex'),
+                sizeBytes: buffer.length,
+                documentId: null,
+                referenceNumber: Number.isFinite(Number(asset.referenceNumber))
+                    ? Math.max(1, Math.floor(Number(asset.referenceNumber)))
+                    : existing?.referenceNumber || null,
+                version: null,
+                isLatest: true,
+                scanStatus: existing?.scanStatus || 'clean',
+                scanEngine: existing?.scanEngine || null,
+                scanDetails: existing?.scanDetails || null,
+                createdByUserId: existing?.createdByUserId || null,
+                createdAt: existing?.createdAt || effectiveUpdatedAt,
+                updatedAt: effectiveUpdatedAt,
+                deletedAt: null,
+                purgeAfter: null,
+                allowReferenceNumberReassignment: options?.allowReferenceNumberReassignment === true
+            });
+            const taskId = String(asset.taskId || '').trim();
+            reconcileWorkspaceSyncLinks({
+                workspaceId,
+                assetId: assetRecord.assetId,
+                taskId,
+                displayName: typeof asset.caption === 'string' && asset.caption.trim().length > 0 ? asset.caption.trim() : null,
+                role: asset.linkRole === 'reference' ? 'reference' : asset.kind === 'image' ? 'image' : 'attachment',
+                updatedAt: effectiveUpdatedAt
+            });
+        }
+        catch (error) {
+            recordSyncDiagnostic(workspaceId, 'apply', 'Failed to persist binary asset metadata after write.', {
+                source: 'assets.write.upsertAsset',
+                path: normalizedPath,
+                assetId: typeof asset.assetId === 'string' ? asset.assetId : null,
+                kind: asset.kind,
+                error: String(error?.message || error || '')
+            });
+        }
+    };
+    const deleteWorkspaceSyncBinaryAsset = (basePath, assetPath, workspaceId = 'default') => {
+        const normalizedPath = normalizeTaskDataRelativePath(assetPath);
+        if (!normalizedPath)
+            return;
+        const root = path.resolve(basePath);
+        const targetPath = path.resolve(root, normalizedPath);
+        const objectStorageClient = getObjectStorageClient();
+        try {
+            if (objectStorageClient) {
+                void objectStorageClient.deleteObject(normalizedPath);
+            }
+            else if (targetPath === root || targetPath.startsWith(`${root}${path.sep}`)) {
+                if (fs.existsSync(targetPath))
+                    fs.unlinkSync(targetPath);
+            }
+        }
+        catch (error) {
+            recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete workspace sync binary asset.', {
+                source: 'assets.delete.file',
+                path: normalizedPath,
+                error: String(error?.message || error || '')
+            });
+        }
+        if (workspaceAssetStore) {
+            const existing = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+            if (existing) {
+                const deletedAt = new Date().toISOString();
+                workspaceAssetStore.markDeleted(existing.assetId, workspaceId, deletedAt);
+                if (existing.kind === 'image') {
+                    core.deleteAnnotatedAttachmentSessionsForImage({
+                        workspaceId,
+                        imageAssetId: existing.assetId,
+                        deletedAt,
+                    });
+                }
+                const links = workspaceAssetStore.listLinksForAsset(existing.assetId, workspaceId, { includeDeleted: true });
+                for (const link of links) {
+                    workspaceAssetStore.deleteLink({
+                        workspaceId,
+                        assetId: existing.assetId,
+                        taskId: link.taskId,
+                        role: link.role
+                    });
+                }
+            }
+        }
+    };
+    const deleteWorkspaceSyncDocument = (basePath, docPath, workspaceId = 'default') => {
+        const normalizedPath = normalizeWorkspaceSyncDocumentPath(docPath);
+        if (!normalizedPath)
+            return;
+        const root = path.resolve(basePath);
+        const targetPath = path.resolve(root, normalizedPath);
+        if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`))
+            return;
+        const objectStorageClient = getObjectStorageClient();
+        try {
+            if (objectStorageClient) {
+                void objectStorageClient.deleteObject(normalizedPath);
+            }
+            else if (fs.existsSync(targetPath)) {
+                fs.unlinkSync(targetPath);
+            }
+        }
+        catch (error) {
+            recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete workspace sync document.', {
+                source: 'documents.delete.file',
+                path: normalizedPath,
+                error: String(error?.message || error || '')
+            });
+        }
+        try {
+            core.deleteDocumentWatermark(workspaceId, normalizedPath);
+            if (workspaceAssetStore) {
+                const existing = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+                if (existing) {
+                    const deletedAt = new Date().toISOString();
+                    workspaceAssetStore.markDeleted(existing.assetId, workspaceId, deletedAt);
+                    if (existing.kind === 'image') {
+                        core.deleteAnnotatedAttachmentSessionsForImage({
+                            workspaceId,
+                            imageAssetId: existing.assetId,
+                            deletedAt,
+                        });
+                    }
+                    const links = workspaceAssetStore.listLinksForAsset(existing.assetId, workspaceId, { includeDeleted: true });
+                    for (const link of links) {
+                        workspaceAssetStore.deleteLink({
+                            workspaceId,
+                            assetId: existing.assetId,
+                            taskId: link.taskId,
+                            role: link.role
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document watermark.', {
+                source: 'documents.delete.watermark',
+                path: normalizedPath,
+                error: String(error?.message || error || '')
+            });
+        }
+        workspaceDocumentSnapshotCache.get(workspaceId)?.delete(normalizedPath);
+    };
+    const resolveConflictOrdering = (incomingWatermark, existingWatermark, incomingTieBreak, existingTieBreak) => (compareWorkspaceMutationOrdering(incomingWatermark, existingWatermark, incomingTieBreak, existingTieBreak));
+    const dispatchWorkspaceSyncChanges = async (workspaceId, incomingChanges, options) => {
+        const tasks = [];
+        const archived = [];
+        const incomingTaskDeletes = new Map();
+        const emittedEventIds = new Set();
+        const unsubscribeRealtime = core.onRealtimeMutation((event) => {
+            const eventWorkspaceId = String(event?.workspaceId || '').trim();
+            if (eventWorkspaceId !== workspaceId)
+                return;
+            const eventId = String(event?.eventId || '').trim();
+            if (eventId)
+                emittedEventIds.add(eventId);
+        });
+        let incomingTaxonomies = null;
+        let incomingTaxonomyState = null;
+        let incomingTaxonomiesUpdatedAt = '';
+        const incomingInitiatives = new Map();
+        const incomingWorkstreams = new Map();
+        const incomingAiProfiles = new Map();
+        const incomingDocuments = [];
+        const incomingDocumentDeletes = new Map();
+        const incomingDocumentReviewSessions = new Map();
+        const incomingDocumentReviewSessionDeletes = new Map();
+        const incomingDocumentReviewComments = new Map();
+        const incomingDocumentReviewCommentDeletes = new Map();
+        const incomingAnnotatedAttachmentSessions = new Map();
+        const incomingAnnotatedAttachmentSessionDeletes = new Map();
+        const incomingAssets = [];
+        const incomingAssetDeletes = new Map();
+        try {
+            for (const change of incomingChanges) {
+                const raw = change;
+                const op = String(raw.op || '').trim().toLowerCase();
+                if (op === 'taxonomy-upsert') {
+                    if (raw.taxonomyState && typeof raw.taxonomyState === 'object' && !Array.isArray(raw.taxonomyState)) {
+                        incomingTaxonomyState = raw.taxonomyState;
+                        incomingTaxonomiesUpdatedAt = String(raw.updatedAt || raw.watermark || '').trim();
+                    }
+                    else if (Array.isArray(raw.taxonomies)) {
+                        incomingTaxonomies = raw.taxonomies;
+                        incomingTaxonomiesUpdatedAt = String(raw.updatedAt || raw.watermark || '').trim();
+                    }
+                    continue;
+                }
+                if (op === 'initiative-upsert') {
+                    const initiative = raw.initiative && typeof raw.initiative === 'object'
+                        ? raw.initiative
+                        : null;
+                    const initiativeId = String(initiative?.id || '').trim();
+                    if (initiativeId) {
+                        incomingInitiatives.set(initiativeId, {
+                            id: initiativeId,
+                            referenceNumber: Number.isFinite(Number(initiative?.referenceNumber))
+                                ? Math.max(1, Math.floor(Number(initiative?.referenceNumber)))
+                                : null,
+                            referenceLabel: typeof initiative?.referenceLabel === 'string' ? initiative.referenceLabel.trim() : undefined,
+                            title: String(initiative?.title || '').trim(),
+                            description: typeof initiative?.description === 'string' ? initiative.description : null,
+                            ownerId: typeof initiative?.ownerId === 'string' ? initiative.ownerId.trim() : null,
+                            createdAt: String(initiative?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
+                            updatedAt: String(initiative?.updatedAt || raw.updatedAt || raw.watermark || initiative?.createdAt || '').trim(),
+                            order: Number.isFinite(Number(initiative?.order)) ? Math.floor(Number(initiative?.order)) : null,
+                            isArchived: Boolean(initiative?.isArchived)
+                        });
+                    }
+                    continue;
+                }
+                if (op === 'workstream-upsert') {
+                    const workstream = raw.workstream && typeof raw.workstream === 'object'
+                        ? raw.workstream
+                        : null;
+                    const workstreamId = String(workstream?.id || '').trim();
+                    if (workstreamId) {
+                        incomingWorkstreams.set(workstreamId, {
+                            id: workstreamId,
+                            referenceNumber: Number.isFinite(Number(workstream?.referenceNumber))
+                                ? Math.max(1, Math.floor(Number(workstream?.referenceNumber)))
+                                : null,
+                            referenceLabel: typeof workstream?.referenceLabel === 'string' ? workstream.referenceLabel.trim() : undefined,
+                            initiativeId: typeof workstream?.initiativeId === 'string' && workstream.initiativeId.trim().length > 0
+                                ? workstream.initiativeId.trim()
+                                : null,
+                            title: String(workstream?.title || '').trim(),
+                            description: typeof workstream?.description === 'string' ? workstream.description : null,
+                            ownerId: typeof workstream?.ownerId === 'string' ? workstream.ownerId.trim() : null,
+                            createdAt: String(workstream?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
+                            updatedAt: String(workstream?.updatedAt || raw.updatedAt || raw.watermark || workstream?.createdAt || '').trim(),
+                            order: Number.isFinite(Number(workstream?.order)) ? Math.floor(Number(workstream?.order)) : null,
+                            isArchived: Boolean(workstream?.isArchived)
+                        });
+                    }
+                    continue;
+                }
+                if (op === 'ai-profile-upsert') {
+                    const profile = raw.profile && typeof raw.profile === 'object'
+                        ? raw.profile
+                        : null;
+                    const profileId = String(profile?.id || '').trim();
+                    if (profileId) {
+                        const profileWorkspaceId = String(profile?.workspaceId || '').trim();
+                        if (profileWorkspaceId && profileWorkspaceId !== workspaceId) {
+                            recordSyncDiagnostic(workspaceId, 'apply', `Rejected ai-profile-upsert for profile ${profileId}: workspace mismatch (expected ${workspaceId}, got ${profileWorkspaceId}).`, {
+                                source: 'apply.aiProfileWorkspaceMismatch',
+                                workspaceId,
+                                profileId,
+                                expectedWorkspaceId: workspaceId,
+                                receivedWorkspaceId: profileWorkspaceId
+                            });
+                            continue;
+                        }
+                        incomingAiProfiles.set(profileId, {
+                            id: profileId,
+                            workspaceId,
+                            profileToken: String(profile?.profileToken || '').trim(),
+                            name: String(profile?.name || '').trim(),
+                            username: String(profile?.username || '').trim(),
+                            icon: String(profile?.icon || 'Bot').trim() || 'Bot',
+                            color: String(profile?.color || '#8b5cf6').trim() || '#8b5cf6',
+                            surfaceType: normalizeIncomingAiProfileSurfaceType(profile?.surfaceType, {
+                                source: 'apply.aiProfileUpsert',
+                                profileId,
+                                workspaceId
+                            }),
+                            providerMetadata: profile?.providerMetadata && typeof profile.providerMetadata === 'object' && !Array.isArray(profile.providerMetadata)
+                                ? profile.providerMetadata
+                                : null,
+                            createdAt: String(profile?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
+                            updatedAt: String(profile?.updatedAt || raw.updatedAt || raw.watermark || '').trim(),
+                            lastActiveAt: typeof profile?.lastActiveAt === 'string' && profile.lastActiveAt.trim().length > 0
+                                ? profile.lastActiveAt.trim()
+                                : null
+                        });
+                    }
+                    continue;
+                }
+                if (op === 'document-upsert') {
+                    const normalizedPath = normalizeWorkspaceSyncDocumentPath(raw.path);
+                    if (normalizedPath) {
+                        incomingDocuments.push({
+                            path: normalizedPath,
+                            updatedAt: String(raw.updatedAt || raw.watermark || '').trim(),
+                            content: typeof raw.content === 'string' ? raw.content : '',
+                            assetId: typeof raw.assetId === 'string' ? raw.assetId.trim() : undefined,
+                            documentId: typeof raw.documentId === 'string' ? raw.documentId.trim() : null,
+                            referenceNumber: Number.isFinite(Number(raw.referenceNumber))
+                                ? Math.max(1, Math.floor(Number(raw.referenceNumber)))
+                                : null,
+                            version: Number.isFinite(Number(raw.version)) ? Math.max(1, Math.floor(Number(raw.version))) : null,
+                            taskId: typeof raw.taskId === 'string' ? raw.taskId.trim() : null,
+                            logicalName: typeof raw.logicalName === 'string' ? raw.logicalName.trim() : null,
+                            caption: typeof raw.caption === 'string' ? raw.caption.trim() : null,
+                            originalFilename: typeof raw.originalFilename === 'string' ? raw.originalFilename.trim() : null,
+                            linkRole: raw.linkRole === 'reference' ? 'reference' : 'attachment'
+                        });
+                    }
+                    continue;
+                }
+                if (op === 'document-delete') {
+                    const normalizedPath = normalizeWorkspaceSyncDocumentPath(raw.path);
+                    if (normalizedPath) {
+                        incomingDocumentDeletes.set(normalizedPath, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
+                    }
+                    continue;
+                }
+                if (op === 'asset-upsert') {
+                    const normalizedPath = normalizeTaskDataRelativePath(String(raw.path || '').trim());
+                    if (normalizedPath) {
+                        incomingAssets.push({
+                            path: normalizedPath,
+                            updatedAt: String(raw.updatedAt || raw.watermark || '').trim(),
+                            contentBase64: typeof raw.contentBase64 === 'string' ? raw.contentBase64 : '',
+                            assetId: typeof raw.assetId === 'string' ? raw.assetId.trim() : undefined,
+                            kind: raw.kind === 'image' ? 'image' : 'file',
+                            mimeType: typeof raw.mimeType === 'string' ? raw.mimeType.trim() : 'application/octet-stream',
+                            referenceNumber: Number.isFinite(Number(raw.referenceNumber))
+                                ? Math.max(1, Math.floor(Number(raw.referenceNumber)))
+                                : null,
+                            taskId: typeof raw.taskId === 'string' ? raw.taskId.trim() : null,
+                            logicalName: typeof raw.logicalName === 'string' ? raw.logicalName.trim() : null,
+                            caption: typeof raw.caption === 'string' ? raw.caption.trim() : null,
+                            originalFilename: typeof raw.originalFilename === 'string' ? raw.originalFilename.trim() : null,
+                            linkRole: raw.linkRole === 'reference' ? 'reference' : raw.linkRole === 'image' ? 'image' : 'attachment'
+                        });
+                    }
+                    continue;
+                }
+                if (op === 'asset-delete') {
+                    const normalizedPath = normalizeTaskDataRelativePath(String(raw.path || '').trim());
+                    if (normalizedPath) {
+                        incomingAssetDeletes.set(normalizedPath, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
+                    }
+                    continue;
+                }
+                if (op === 'document-review-session-upsert') {
+                    const session = raw.session && typeof raw.session === 'object'
+                        ? raw.session
+                        : null;
+                    const sessionId = String(session?.id || '').trim();
+                    const assetId = String(session?.assetId || '').trim();
+                    if (sessionId && assetId) {
+                        incomingDocumentReviewSessions.set(sessionId, {
+                            id: sessionId,
+                            assetId,
+                            documentId: typeof session?.documentId === 'string' ? session.documentId.trim() : null,
+                            documentVersion: Number.isFinite(Number(session?.documentVersion)) ? Math.max(1, Math.floor(Number(session?.documentVersion))) : null,
+                            title: typeof session?.title === 'string' ? session.title.trim() : null,
+                            status: session?.status === 'resolved' ? 'resolved' : 'open',
+                            comments: Array.isArray(session?.comments) ? session.comments : [],
+                            createdByActorId: typeof session?.createdByActorId === 'string' ? session.createdByActorId.trim() : null,
+                            updatedByActorId: typeof session?.updatedByActorId === 'string' ? session.updatedByActorId.trim() : null,
+                            createdAt: String(session?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
+                            updatedAt: String(session?.updatedAt || raw.updatedAt || raw.watermark || session?.createdAt || '').trim(),
+                            deletedAt: typeof session?.deletedAt === 'string' && session.deletedAt.trim().length > 0 ? session.deletedAt.trim() : null,
+                        });
+                    }
+                    continue;
+                }
+                if (op === 'document-review-session-delete') {
+                    const sessionId = String(raw.sessionId || raw.id || '').trim();
+                    if (sessionId) {
+                        incomingDocumentReviewSessionDeletes.set(sessionId, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
+                    }
+                    continue;
+                }
+                if (op === 'document-review-comment-upsert') {
+                    const comment = raw.comment && typeof raw.comment === 'object'
+                        ? raw.comment
+                        : null;
+                    const commentId = String(comment?.id || '').trim();
+                    const sessionId = String(comment?.sessionId || '').trim();
+                    if (commentId && sessionId) {
+                        incomingDocumentReviewComments.set(commentId, {
+                            id: commentId,
+                            sessionId,
+                            body: typeof comment?.body === 'string' ? comment.body : '',
+                            anchor: comment?.anchor ?? null,
+                            order: Number.isFinite(Number(comment?.order)) ? Math.max(0, Math.floor(Number(comment?.order))) : 0,
+                            authorActorId: typeof comment?.authorActorId === 'string' ? comment.authorActorId.trim() : null,
+                            createdAt: String(comment?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
+                            updatedAt: String(comment?.updatedAt || raw.updatedAt || raw.watermark || comment?.createdAt || '').trim(),
+                            deletedAt: typeof comment?.deletedAt === 'string' && comment.deletedAt.trim().length > 0 ? comment.deletedAt.trim() : null,
+                        });
+                    }
+                    continue;
+                }
+                if (op === 'document-review-comment-delete') {
+                    const commentId = String(raw.commentId || raw.id || '').trim();
+                    if (commentId) {
+                        incomingDocumentReviewCommentDeletes.set(commentId, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
+                    }
+                    continue;
+                }
+                if (op === 'annotated-attachment-session-upsert') {
+                    const session = raw.session && typeof raw.session === 'object'
+                        ? raw.session
+                        : null;
+                    const sessionId = String(session?.id || '').trim();
+                    const sessionWorkspaceId = String(session?.workspaceId || '').trim();
+                    const taskId = String(session?.taskId || '').trim();
+                    const baseImageAssetId = String(session?.baseImageAssetId || '').trim();
+                    if (sessionId
+                        && sessionWorkspaceId === workspaceId
+                        && baseImageAssetId) {
+                        incomingAnnotatedAttachmentSessions.set(sessionId, {
+                            id: sessionId,
+                            workspaceId: sessionWorkspaceId,
+                            taskId,
+                            baseImageAssetId,
+                            title: typeof session?.title === 'string' ? session.title.trim() : null,
+                            globalInstruction: typeof session?.globalInstruction === 'string' ? session.globalInstruction.trim() : null,
+                            annotations: Array.isArray(session?.annotations) ? session.annotations : [],
+                            createdByActorId: typeof session?.createdByActorId === 'string' ? session.createdByActorId.trim() : null,
+                            updatedByActorId: typeof session?.updatedByActorId === 'string' ? session.updatedByActorId.trim() : null,
+                            createdAt: String(session?.createdAt || raw.updatedAt || raw.watermark || '').trim(),
+                            updatedAt: String(session?.updatedAt || raw.updatedAt || raw.watermark || session?.createdAt || '').trim(),
+                            deletedAt: typeof session?.deletedAt === 'string' && session.deletedAt.trim().length > 0 ? session.deletedAt.trim() : null,
+                        });
+                    }
+                    continue;
+                }
+                if (op === 'annotated-attachment-session-delete') {
+                    const sessionId = String(raw.sessionId || raw.id || '').trim();
+                    if (sessionId) {
+                        incomingAnnotatedAttachmentSessionDeletes.set(sessionId, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
+                    }
+                    continue;
+                }
+                if (op !== 'delete')
+                    continue;
+                const task = raw.task;
+                const deleteTaskId = String(raw.taskId || raw.id || task?.id || '').trim();
+                if (deleteTaskId) {
+                    incomingTaskDeletes.set(deleteTaskId, String(raw.deletedAt || raw.watermark || new Date().toISOString()).trim());
+                }
+            }
+            for (const change of incomingChanges) {
+                const raw = change;
+                const op = String(raw.op || '').trim().toLowerCase();
+                if (op === 'delete'
+                    || op === 'initiative-upsert'
+                    || op === 'workstream-upsert'
+                    || op === 'document-upsert'
+                    || op === 'document-delete'
+                    || op === 'asset-upsert'
+                    || op === 'asset-delete'
+                    || op === 'document-review-session-upsert'
+                    || op === 'document-review-session-delete'
+                    || op === 'document-review-comment-upsert'
+                    || op === 'document-review-comment-delete'
+                    || op === 'annotated-attachment-session-upsert'
+                    || op === 'annotated-attachment-session-delete')
+                    continue;
+                const task = raw.task && typeof raw.task === 'object' ? raw.task : null;
+                if (!task)
+                    continue;
+                const taskId = String(task.id || '').trim();
+                const deleteWatermark = taskId ? String(incomingTaskDeletes.get(taskId) || '').trim() : '';
+                if (taskId && deleteWatermark) {
+                    const compareAgainstDelete = resolveConflictOrdering(deleteWatermark, String(task.updatedAt || task.createdAt || '').trim(), `delete:${taskId}`, getTaskMutationTieBreak(task, raw.archived === true || task?.isArchived === true));
+                    if (compareAgainstDelete >= 0)
+                        continue;
+                }
+                const markedArchived = raw.archived === true || task?.isArchived === true;
+                if (markedArchived)
+                    archived.push(task);
+                else
+                    tasks.push(task);
+            }
+            for (const [taskId, deleteWatermark] of incomingTaskDeletes.entries()) {
+                try {
+                    const existingTask = core.getTask(taskId, workspaceId);
+                    if (existingTask) {
+                        const compareAgainstExisting = resolveConflictOrdering(deleteWatermark, getTaskMutationWatermark(existingTask), `delete:${taskId}`, getTaskMutationTieBreak(existingTask, Boolean(existingTask.isArchived)));
+                        if (compareAgainstExisting < 0)
+                            continue;
+                    }
+                    core.deleteTaskForSync(taskId, workspaceId, { persistBackup: false });
+                }
+                catch (error) {
+                    recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete task during sync apply.', {
+                        source: 'apply.deleteTask',
+                        taskId,
+                        error: String(error?.message || error || '')
+                    });
+                }
+            }
+            if (incomingInitiatives.size > 0) {
+                for (const initiative of incomingInitiatives.values()) {
+                    try {
+                        core.upsertInitiativeForSync({
+                            id: initiative.id,
+                            referenceNumber: initiative.referenceNumber,
+                            referenceLabel: initiative.referenceLabel,
+                            title: initiative.title,
+                            description: initiative.description,
+                            ownerId: initiative.ownerId,
+                            createdAt: initiative.createdAt,
+                            updatedAt: initiative.updatedAt,
+                            order: initiative.order,
+                            isArchived: initiative.isArchived
+                        }, workspaceId);
+                    }
+                    catch (error) {
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert initiative during sync apply.', {
+                            source: 'apply.initiativeUpsert',
+                            initiativeId: initiative.id,
+                            error: String(error?.message || error || '')
+                        });
+                        throw error;
+                    }
+                }
+            }
+            if (incomingWorkstreams.size > 0) {
+                for (const workstream of incomingWorkstreams.values()) {
+                    try {
+                        core.upsertWorkstreamForSync({
+                            id: workstream.id,
+                            referenceNumber: workstream.referenceNumber,
+                            referenceLabel: workstream.referenceLabel,
+                            initiativeId: workstream.initiativeId,
+                            title: workstream.title,
+                            description: workstream.description,
+                            ownerId: workstream.ownerId,
+                            createdAt: workstream.createdAt,
+                            updatedAt: workstream.updatedAt,
+                            order: workstream.order,
+                            isArchived: workstream.isArchived
+                        }, workspaceId);
+                    }
+                    catch (error) {
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert workstream during sync apply.', {
+                            source: 'apply.workstreamUpsert',
+                            workstreamId: workstream.id,
+                            error: String(error?.message || error || '')
+                        });
+                        throw error;
+                    }
+                }
+            }
+            if (incomingTaxonomyState || Array.isArray(incomingTaxonomies)) {
+                const nextTaxonomyState = incomingTaxonomyState || { taxonomies: incomingTaxonomies || [] };
+                if (!incomingTaxonomiesUpdatedAt) {
+                    if (typeof core.updateTaxonomyState === 'function') {
+                        core.updateTaxonomyState(nextTaxonomyState, workspaceId);
+                    }
+                    else {
+                        core.updateTaxonomies(Array.isArray(incomingTaxonomies) ? incomingTaxonomies : []);
+                    }
+                    const fallbackHash = createHash('sha256').update(JSON.stringify(nextTaxonomyState)).digest('hex');
+                    workspaceTaxonomySyncMeta.set(workspaceId, {
+                        updatedAt: new Date().toISOString(),
+                        hash: fallbackHash
+                    });
+                }
+                else {
+                    const incomingTaxonomyHash = createHash('sha256').update(JSON.stringify(nextTaxonomyState)).digest('hex');
+                    const currentMeta = workspaceTaxonomySyncMeta.get(workspaceId) || { updatedAt: '', hash: '' };
+                    const compare = resolveConflictOrdering(incomingTaxonomiesUpdatedAt, currentMeta.updatedAt, incomingTaxonomyHash, currentMeta.hash);
+                    if (compare >= 0) {
+                        if (typeof core.updateTaxonomyState === 'function') {
+                            core.updateTaxonomyState(nextTaxonomyState, workspaceId);
+                        }
+                        else {
+                            core.updateTaxonomies(Array.isArray(incomingTaxonomies) ? incomingTaxonomies : []);
+                        }
+                        workspaceTaxonomySyncMeta.set(workspaceId, {
+                            updatedAt: incomingTaxonomiesUpdatedAt,
+                            hash: incomingTaxonomyHash
+                        });
+                    }
+                }
+            }
+            if (incomingAiProfiles.size > 0) {
+                for (const profile of incomingAiProfiles.values()) {
+                    try {
+                        core.upsertAiProfileForSync({
+                            id: profile.id,
+                            workspaceId: workspaceId,
+                            profileToken: profile.profileToken,
+                            name: profile.name,
+                            username: profile.username,
+                            icon: profile.icon,
+                            color: profile.color,
+                            surfaceType: profile.surfaceType,
+                            providerMetadata: profile.providerMetadata,
+                            createdAt: profile.createdAt,
+                            updatedAt: profile.updatedAt,
+                            lastActiveAt: profile.lastActiveAt
+                        });
+                    }
+                    catch (error) {
+                        const details = {
+                            source: 'apply.aiProfileUpsert',
+                            workspaceId,
+                            profileId: profile.id,
+                            error: String(error?.message || error || ''),
+                            errorCode: String(error?.code || '').trim() || null
+                        };
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert AI profile during sync apply.', details);
+                        throw createSyncRouteError(`Failed to persist AI profile ${profile.id} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'AI_PROFILE_SYNC_APPLY_FAILED', statusCode: 500 });
+                    }
+                }
+                assertSyncedAiProfilesPersisted(workspaceId, incomingAiProfiles);
+            }
+            if (Array.isArray(options?.workspaceMembers)) {
+                core.replaceWorkspaceUsersForSync({
+                    workspaceId,
+                    users: options.workspaceMembers
+                        .filter((member) => String(member?.workspaceId || workspaceId).trim() === workspaceId)
+                        .map((member) => ({
+                        userId: member.userId,
+                        email: member.email,
+                        displayName: member.displayName,
+                        role: member.role,
+                        permissionMode: member.permissionMode,
+                        betaAccess: member.betaAccess,
+                        status: member.status,
+                        disabled: member.disabled,
+                        createdAt: member.createdAt,
+                        updatedAt: member.updatedAt,
+                        emailVerifiedAt: member.emailVerifiedAt
+                    }))
+                });
+            }
+            validateTaskActorAssignments(workspaceId, tasks, archived);
+            if (incomingDocuments.length > 0) {
+                for (const doc of incomingDocuments) {
+                    try {
+                        const existingDoc = core.getDocumentWatermark(workspaceId, doc.path);
+                        const incomingHash = createHash('sha256').update(String(doc.content || '')).digest('hex');
+                        const existingUpdatedAt = String(existingDoc?.updatedAt || '').trim();
+                        const existingHash = String(existingDoc?.contentHash || '').trim();
+                        const compare = resolveConflictOrdering(doc.updatedAt, existingUpdatedAt, incomingHash, existingHash);
+                        const metadataDrift = hasDocumentSyncMetadataDrift(workspaceId, doc, options);
+                        if (compare < 0)
+                            continue;
+                        if (compare === 0 && existingHash === incomingHash && !metadataDrift)
+                            continue;
+                        await writeWorkspaceSyncDocument(core.getPaths().basePath, doc, workspaceId, options);
+                    }
+                    catch (error) {
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to apply synced document change.', {
+                            source: 'documents.apply.write',
+                            path: doc.path,
+                            assetId: typeof doc.assetId === 'string' ? doc.assetId : null,
+                            error: String(error?.message || error || '')
+                        });
+                    }
+                }
+            }
+            if (incomingDocumentDeletes.size > 0) {
+                for (const [docPath, deletedAt] of incomingDocumentDeletes.entries()) {
+                    const existingDoc = core.getDocumentWatermark(workspaceId, docPath);
+                    const existingUpdatedAt = String(existingDoc?.updatedAt || '').trim();
+                    const existingHash = String(existingDoc?.contentHash || '').trim();
+                    const compare = resolveConflictOrdering(deletedAt, existingUpdatedAt, `delete:${docPath}`, existingHash);
+                    if (existingDoc && compare < 0)
+                        continue;
+                    deleteWorkspaceSyncDocument(core.getPaths().basePath, docPath, workspaceId);
+                }
+            }
+            if (incomingAssets.length > 0) {
+                for (const asset of incomingAssets) {
+                    try {
+                        const existing = workspaceAssetStore?.getByStorageKey(asset.path, workspaceId);
+                        const incomingHash = createHash('sha256').update(Buffer.from(String(asset.contentBase64 || ''), 'base64')).digest('hex');
+                        const existingUpdatedAt = String(existing?.updatedAt || '').trim();
+                        const existingHash = String(existing?.contentSha256 || '').trim();
+                        const assetPath = path.resolve(core.getPaths().basePath, asset.path);
+                        const localFileMissing = !getObjectStorageClient() && !fs.existsSync(assetPath);
+                        const compare = resolveConflictOrdering(asset.updatedAt, existingUpdatedAt, incomingHash, existingHash);
+                        const metadataDrift = hasBinaryAssetSyncMetadataDrift(workspaceId, asset, options);
+                        if (compare < 0)
+                            continue;
+                        if (compare === 0 && existingHash === incomingHash && !localFileMissing && !metadataDrift)
+                            continue;
+                        await writeWorkspaceSyncBinaryAsset(core.getPaths().basePath, asset, workspaceId, options);
+                    }
+                    catch (error) {
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to apply synced asset change.', {
+                            source: 'assets.apply.write',
+                            path: asset.path,
+                            assetId: typeof asset.assetId === 'string' ? asset.assetId : null,
+                            kind: asset.kind,
+                            error: String(error?.message || error || '')
+                        });
+                    }
+                }
+            }
+            if (incomingAssetDeletes.size > 0) {
+                for (const [assetPath, deletedAt] of incomingAssetDeletes.entries()) {
+                    const existing = workspaceAssetStore?.getByStorageKey(assetPath, workspaceId);
+                    const existingUpdatedAt = String(existing?.updatedAt || '').trim();
+                    const existingHash = String(existing?.contentSha256 || '').trim();
+                    const compare = resolveConflictOrdering(deletedAt, existingUpdatedAt, `delete:${assetPath}`, existingHash);
+                    if (existing && compare < 0)
+                        continue;
+                    deleteWorkspaceSyncBinaryAsset(core.getPaths().basePath, assetPath, workspaceId);
+                }
+            }
+            if (incomingDocumentReviewSessions.size > 0) {
+                for (const session of incomingDocumentReviewSessions.values()) {
+                    try {
+                        const existing = core.getDocumentReviewSession({
+                            workspaceId,
+                            sessionId: session.id,
+                            includeDeleted: true
+                        });
+                        const incomingTieBreak = createHash('sha256').update(JSON.stringify(session.comments || [])).digest('hex');
+                        const existingTieBreak = existing
+                            ? createHash('sha256').update(JSON.stringify(existing.comments || [])).digest('hex')
+                            : '';
+                        const compare = resolveConflictOrdering(session.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
+                        if (compare < 0)
+                            continue;
+                        core.upsertDocumentReviewSessionForSync({
+                            id: session.id,
+                            tenantId: core.getTenantId(),
+                            workspaceId,
+                            assetId: session.assetId,
+                            documentId: session.documentId,
+                            documentVersion: session.documentVersion,
+                            title: session.title,
+                            status: session.status,
+                            comments: [],
+                            createdByActorId: session.createdByActorId,
+                            updatedByActorId: session.updatedByActorId,
+                            createdAt: session.createdAt,
+                            updatedAt: session.updatedAt,
+                            deletedAt: session.deletedAt,
+                        });
+                    }
+                    catch (error) {
+                        const details = {
+                            source: 'apply.documentReviewUpsert',
+                            sessionId: session.id,
+                            error: String(error?.message || error || ''),
+                            errorCode: String(error?.code || '').trim() || null
+                        };
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert document review session during sync apply.', details);
+                        throw createSyncRouteError(`Failed to persist document review session ${session.id} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'DOCUMENT_REVIEW_SESSION_SYNC_APPLY_FAILED', statusCode: 500 });
+                    }
+                }
+            }
+            if (incomingDocumentReviewComments.size > 0) {
+                for (const comment of incomingDocumentReviewComments.values()) {
+                    try {
+                        const existingComments = core.listDocumentReviewCommentsForSync({
+                            workspaceId,
+                            includeDeleted: true
+                        });
+                        const existing = existingComments.find((entry) => entry.id === comment.id) || null;
+                        const incomingTieBreak = createHash('sha256')
+                            .update(JSON.stringify({ body: comment.body, anchor: comment.anchor, deletedAt: comment.deletedAt }))
+                            .digest('hex');
+                        const existingTieBreak = existing
+                            ? createHash('sha256')
+                                .update(JSON.stringify({ body: existing.body, anchor: existing.anchor, deletedAt: existing.deletedAt }))
+                                .digest('hex')
+                            : '';
+                        const compare = resolveConflictOrdering(comment.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
+                        if (compare < 0)
+                            continue;
+                        core.upsertDocumentReviewCommentForSync({
+                            id: comment.id,
+                            tenantId: core.getTenantId(),
+                            workspaceId,
+                            sessionId: comment.sessionId,
+                            body: comment.body,
+                            anchor: comment.anchor,
+                            order: comment.order,
+                            authorActorId: comment.authorActorId,
+                            createdAt: comment.createdAt,
+                            updatedAt: comment.updatedAt,
+                            deletedAt: comment.deletedAt,
+                        });
+                    }
+                    catch (error) {
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert document review comment during sync apply.', {
+                            source: 'apply.documentReviewCommentUpsert',
+                            commentId: comment.id,
+                            error: String(error?.message || error || '')
+                        });
+                        throw error;
+                    }
+                }
+            }
+            if (incomingDocumentReviewSessionDeletes.size > 0) {
+                for (const [sessionId, deletedAt] of incomingDocumentReviewSessionDeletes.entries()) {
+                    try {
+                        const existing = core.getDocumentReviewSession({
+                            workspaceId,
+                            sessionId,
+                            includeDeleted: true
+                        });
+                        const compare = resolveConflictOrdering(deletedAt, String(existing?.updatedAt || '').trim(), `delete:${sessionId}`, String(existing?.id || '').trim());
+                        if (existing && compare < 0)
+                            continue;
+                        core.deleteDocumentReviewSessionForSync({ workspaceId, sessionId, deletedAt });
+                    }
+                    catch (error) {
+                        const details = {
+                            source: 'apply.documentReviewDelete',
+                            sessionId,
+                            error: String(error?.message || error || ''),
+                            errorCode: String(error?.code || '').trim() || null
+                        };
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document review session during sync apply.', details);
+                        throw createSyncRouteError(`Failed to delete document review session ${sessionId} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'DOCUMENT_REVIEW_SESSION_SYNC_DELETE_FAILED', statusCode: 500 });
+                    }
+                }
+            }
+            if (incomingDocumentReviewCommentDeletes.size > 0) {
+                for (const [commentId, deletedAt] of incomingDocumentReviewCommentDeletes.entries()) {
+                    try {
+                        const existing = core.listDocumentReviewCommentsForSync({
+                            workspaceId,
+                            includeDeleted: true
+                        }).find((entry) => entry.id === commentId) || null;
+                        const compare = resolveConflictOrdering(deletedAt, String(existing?.updatedAt || '').trim(), `delete:${commentId}`, String(existing?.id || '').trim());
+                        if (existing && compare < 0)
+                            continue;
+                        core.deleteDocumentReviewCommentForSync({ workspaceId, commentId, deletedAt });
+                    }
+                    catch (error) {
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete document review comment during sync apply.', {
+                            source: 'apply.documentReviewCommentDelete',
+                            commentId,
+                            error: String(error?.message || error || '')
+                        });
+                        throw error;
+                    }
+                }
+            }
+            if (incomingAnnotatedAttachmentSessions.size > 0) {
+                for (const session of incomingAnnotatedAttachmentSessions.values()) {
+                    try {
+                        const existing = core.getAnnotatedAttachmentSession({
+                            workspaceId,
+                            sessionId: session.id,
+                            includeDeleted: true
+                        });
+                        const incomingTieBreak = createHash('sha256').update(JSON.stringify(session.annotations || [])).digest('hex');
+                        const existingTieBreak = existing
+                            ? createHash('sha256').update(JSON.stringify(existing.annotations || [])).digest('hex')
+                            : '';
+                        const compare = resolveConflictOrdering(session.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
+                        if (compare < 0)
+                            continue;
+                        core.upsertAnnotatedAttachmentSessionForSync({
+                            id: session.id,
+                            tenantId: core.getTenantId(),
+                            workspaceId,
+                            taskId: session.taskId,
+                            baseImageAssetId: session.baseImageAssetId,
+                            title: session.title,
+                            globalInstruction: session.globalInstruction,
+                            annotations: session.annotations,
+                            createdByActorId: session.createdByActorId,
+                            updatedByActorId: session.updatedByActorId,
+                            createdAt: session.createdAt,
+                            updatedAt: session.updatedAt,
+                            deletedAt: session.deletedAt,
+                        });
+                    }
+                    catch (error) {
+                        const details = {
+                            source: 'apply.annotatedAttachmentUpsert',
+                            sessionId: session.id,
+                            error: String(error?.message || error || ''),
+                            errorCode: String(error?.code || '').trim() || null
+                        };
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to upsert annotated attachment session during sync apply.', details);
+                        throw createSyncRouteError(`Failed to persist annotated attachment session ${session.id} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'ANNOTATED_ATTACHMENT_SESSION_SYNC_APPLY_FAILED', statusCode: 500 });
+                    }
+                }
+            }
+            if (incomingAnnotatedAttachmentSessionDeletes.size > 0) {
+                for (const [sessionId, deletedAt] of incomingAnnotatedAttachmentSessionDeletes.entries()) {
+                    try {
+                        const existing = core.getAnnotatedAttachmentSession({
+                            workspaceId,
+                            sessionId,
+                            includeDeleted: true
+                        });
+                        const compare = resolveConflictOrdering(deletedAt, String(existing?.updatedAt || '').trim(), `delete:${sessionId}`, String(existing?.id || '').trim());
+                        if (existing && compare < 0)
+                            continue;
+                        core.deleteAnnotatedAttachmentSessionForSync({ workspaceId, sessionId, deletedAt });
+                    }
+                    catch (error) {
+                        const details = {
+                            source: 'apply.annotatedAttachmentDelete',
+                            sessionId,
+                            error: String(error?.message || error || ''),
+                            errorCode: String(error?.code || '').trim() || null
+                        };
+                        recordSyncDiagnostic(workspaceId, 'apply', 'Failed to delete annotated attachment session during sync apply.', details);
+                        throw createSyncRouteError(`Failed to delete annotated attachment session ${sessionId} during sync apply: ${String(error?.message || error || 'Unknown error')}`, details, { code: 'ANNOTATED_ATTACHMENT_SESSION_SYNC_DELETE_FAILED', statusCode: 500 });
+                    }
+                }
+            }
+            if (incomingDocuments.length > 0 || incomingAssets.length > 0) {
+                core.notifyDocumentMetadataMutation(workspaceId, [
+                    ...incomingDocuments.map((entry) => entry.path),
+                    ...incomingAssets.map((entry) => entry.path)
+                ], 'upsert');
+            }
+            if (incomingDocumentDeletes.size > 0 || incomingAssetDeletes.size > 0) {
+                core.notifyDocumentMetadataMutation(workspaceId, [
+                    ...Array.from(incomingDocumentDeletes.keys()),
+                    ...Array.from(incomingAssetDeletes.keys())
+                ], 'delete');
+            }
+            const result = core.applyWorkspaceSyncSnapshot({ tasks, archived }, workspaceId);
+            return { result, deleteCount: incomingTaskDeletes.size, emittedEventIds: Array.from(emittedEventIds) };
+        }
+        finally {
+            unsubscribeRealtime();
+        }
+    };
+    // GET /api/taskforce/sync/user-settings - Pull user-global sync payload for authenticated user
+    addRoute('GET', '/api/taskforce/sync/user-settings', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (!authConfig || !authConfig.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Sync is unavailable when auth is disabled.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const snapshot = core.getUserGlobalSyncSettings(access.userId);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            settings: snapshot.settings,
+            updatedAt: snapshot.updatedAt
+        }));
+    });
+    // POST /api/taskforce/sync/user-settings - Push user-global sync payload for authenticated user
+    addRoute('POST', '/api/taskforce/sync/user-settings', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (!authConfig || !authConfig.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Sync is unavailable when auth is disabled.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req, 50 * 1024 * 1024);
+        const incomingSettings = body?.settings;
+        const incomingUpdatedAt = typeof body?.updatedAt === 'string' ? body.updatedAt : undefined;
+        const result = core.upsertUserGlobalSyncSettings(access.userId, incomingSettings, incomingUpdatedAt);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            settings: result.settings,
+            updatedAt: result.updatedAt,
+            applied: result.applied
+        }));
+    });
+    // POST /api/taskforce/sync/workspace/handshake - Enforce workspace-id match before workspace sync
+    addRoute('POST', '/api/taskforce/sync/workspace/handshake', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (!authConfig || !authConfig.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Sync is unavailable when auth is disabled.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+            auditAuthAction(req, 'sync-workspace-handshake-unauthorized', {});
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const localWorkspaceId = String(body?.workspaceId || '').trim();
+        if (!localWorkspaceId) {
+            auditAuthAction(req, 'sync-workspace-handshake-invalid', { code: 'WORKSPACE_ID_REQUIRED' });
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'workspaceId is required.' }));
+            return;
+        }
+        const cloudWorkspaceId = String(access.workspaceId || '').trim();
+        if (!cloudWorkspaceId) {
+            auditAuthAction(req, 'sync-workspace-handshake-missing-cloud-workspace', { code: 'WORKSPACE_ID_REQUIRED' });
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'No cloud workspace is selected. Complete workspace setup first.',
+                code: 'WORKSPACE_ID_REQUIRED'
+            }));
+            return;
+        }
+        if (localWorkspaceId !== cloudWorkspaceId) {
+            auditAuthAction(req, 'sync-workspace-handshake-mismatch', {
+                localWorkspaceId,
+                cloudWorkspaceId
+            });
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'Workspace mismatch. Sync requires matching local and cloud workspace IDs.',
+                code: 'WORKSPACE_ID_MISMATCH',
+                localWorkspaceId,
+                cloudWorkspaceId
+            }));
+            return;
+        }
+        auditAuthAction(req, 'sync-workspace-handshake-success', { workspaceId: localWorkspaceId });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            localWorkspaceId,
+            cloudWorkspaceId
+        }));
+    });
+    // POST /api/taskforce/sync/workspace/provision - Switch to existing cloud workspace that matches local workspace id
+    addRoute('POST', '/api/taskforce/sync/workspace/provision', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (!authConfig || !authConfig.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Sync is unavailable when auth is disabled.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        if (!access.authenticated || !access.sessionId || !access.userId || access.userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const requestedWorkspaceId = String(body?.workspaceId || '').trim();
+        const requestedWorkspaceName = String(body?.name || requestedWorkspaceId || '').trim();
+        const requestedWorkspaceDescription = typeof body?.description === 'string' ? body.description : undefined;
+        if (!requestedWorkspaceId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'workspaceId is required.' }));
+            return;
+        }
+        if (isReservedWorkspaceId(requestedWorkspaceId)) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'workspaceId "default" is reserved.',
+                code: 'WORKSPACE_ID_RESERVED'
+            }));
+            return;
+        }
+        if (!requestedWorkspaceName) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'name is required.' }));
+            return;
+        }
+        const existing = core.listUserWorkspaces(access.userId).find((workspace) => workspace.id === requestedWorkspaceId);
+        if (existing) {
+            const cookie = createSessionTokenCookie(access.sessionId, authConfig, {
+                role: existing.role,
+                workspaceId: existing.id,
+                userId: access.userId,
+                ...resolveSessionCookieAttributesForRequest(req, authConfig)
+            });
+            res.setHeader('Set-Cookie', cookie);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: true,
+                workspace: existing,
+                existing: true
+            }));
+            return;
+        }
+        try {
+            const created = core.createWorkspaceForUser({
+                userId: access.userId,
+                name: requestedWorkspaceName,
+                description: requestedWorkspaceDescription,
+                role: 'owner',
+                preferredWorkspaceId: requestedWorkspaceId
+            });
+            const cookie = createSessionTokenCookie(access.sessionId, authConfig, {
+                role: created.role,
+                workspaceId: created.id,
+                userId: access.userId,
+                ...resolveSessionCookieAttributesForRequest(req, authConfig)
+            });
+            res.setHeader('Set-Cookie', cookie);
+            auditAuthAction(req, 'sync-workspace-provision-created', {
+                workspaceId: created.id,
+                workspaceName: created.name
+            });
+            res.writeHead(201, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: true,
+                workspace: created,
+                existing: false
+            }));
+            return;
+        }
+        catch (error) {
+            res.writeHead(resolveErrorStatusCode(error, 400), { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: String(error?.message || 'Unable to provision workspace for sync.'),
+                code: error?.code
+            }));
+            return;
+        }
+    });
+    // POST /api/taskforce/sync/workspace/bootstrap-push - Initial local snapshot push into authenticated cloud workspace
+    addRoute('POST', '/api/taskforce/sync/workspace/bootstrap-push', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (!authConfig || !authConfig.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Sync is unavailable when auth is disabled.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+            auditAuthAction(req, 'sync-workspace-bootstrap-unauthorized', {});
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req, 50 * 1024 * 1024);
+        const requestedWorkspaceId = String(body?.workspaceId || '').trim();
+        const cloudWorkspaceId = String(access.workspaceId || '').trim();
+        if (!requestedWorkspaceId) {
+            auditAuthAction(req, 'sync-workspace-bootstrap-invalid', { code: 'WORKSPACE_ID_REQUIRED' });
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'workspaceId is required.', code: 'WORKSPACE_ID_REQUIRED' }));
+            return;
+        }
+        if (!cloudWorkspaceId) {
+            auditAuthAction(req, 'sync-workspace-bootstrap-missing-workspace', { code: 'WORKSPACE_ID_REQUIRED' });
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'No workspace selected. Create or select a workspace first.',
+                code: 'WORKSPACE_ID_REQUIRED'
+            }));
+            return;
+        }
+        if (requestedWorkspaceId !== cloudWorkspaceId) {
+            auditAuthAction(req, 'sync-workspace-bootstrap-mismatch', {
+                requestedWorkspaceId,
+                cloudWorkspaceId
+            });
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'Workspace mismatch. Sync requires matching local and cloud workspace IDs.',
+                code: 'WORKSPACE_ID_MISMATCH',
+                localWorkspaceId: requestedWorkspaceId,
+                cloudWorkspaceId
+            }));
+            return;
+        }
+        const tasks = Array.isArray(body?.tasks) ? body.tasks : [];
+        const archived = Array.isArray(body?.archived) ? body.archived : [];
+        const incomingInitiatives = Array.isArray(body?.initiatives) ? body.initiatives : [];
+        const incomingWorkstreams = Array.isArray(body?.workstreams) ? body.workstreams : [];
+        const incomingTaxonomies = Array.isArray(body?.taxonomies) ? body.taxonomies : null;
+        const incomingTaxonomyState = body?.taxonomyState && typeof body.taxonomyState === 'object' && !Array.isArray(body.taxonomyState)
+            ? body.taxonomyState
+            : null;
+        const incomingAiProfiles = Array.isArray(body?.aiProfiles) ? body.aiProfiles : [];
+        const incomingDocuments = Array.isArray(body?.documents) ? body.documents : [];
+        const incomingDocumentReviewSessions = Array.isArray(body?.documentReviewSessions) ? body.documentReviewSessions : [];
+        const incomingDocumentReviewComments = Array.isArray(body?.documentReviewComments) ? body.documentReviewComments : [];
+        const incomingAnnotatedAttachmentSessions = Array.isArray(body?.annotatedAttachmentSessions) ? body.annotatedAttachmentSessions : [];
+        const incomingAssets = Array.isArray(body?.assets) ? body.assets : [];
+        try {
+            const bootstrapChanges = [
+                ...((incomingTaxonomyState || incomingTaxonomies) ? [{
+                        op: 'taxonomy-upsert',
+                        taxonomies: incomingTaxonomies,
+                        taxonomyState: incomingTaxonomyState || undefined,
+                        updatedAt: new Date().toISOString()
+                    }] : []),
+                ...incomingInitiatives
+                    .map((initiative) => ({
+                    op: 'initiative-upsert',
+                    initiative: {
+                        id: String(initiative?.id || '').trim(),
+                        referenceNumber: Number.isFinite(Number(initiative?.referenceNumber))
+                            ? Math.max(1, Math.floor(Number(initiative.referenceNumber)))
+                            : null,
+                        referenceLabel: typeof initiative?.referenceLabel === 'string' ? initiative.referenceLabel.trim() : undefined,
+                        title: String(initiative?.title || '').trim(),
+                        description: typeof initiative?.description === 'string' ? initiative.description : null,
+                        ownerId: typeof initiative?.ownerId === 'string' ? initiative.ownerId.trim() : null,
+                        createdAt: String(initiative?.createdAt || '').trim(),
+                        updatedAt: String(initiative?.updatedAt || initiative?.createdAt || '').trim(),
+                        order: Number.isFinite(Number(initiative?.order)) ? Math.floor(Number(initiative.order)) : null,
+                        isArchived: Boolean(initiative?.isArchived)
+                    }
+                }))
+                    .filter((change) => change.initiative.id.length > 0),
+                ...incomingWorkstreams
+                    .map((workstream) => ({
+                    op: 'workstream-upsert',
+                    workstream: {
+                        id: String(workstream?.id || '').trim(),
+                        referenceNumber: Number.isFinite(Number(workstream?.referenceNumber))
+                            ? Math.max(1, Math.floor(Number(workstream.referenceNumber)))
+                            : null,
+                        referenceLabel: typeof workstream?.referenceLabel === 'string' ? workstream.referenceLabel.trim() : undefined,
+                        initiativeId: typeof workstream?.initiativeId === 'string' ? workstream.initiativeId.trim() : null,
+                        title: String(workstream?.title || '').trim(),
+                        description: typeof workstream?.description === 'string' ? workstream.description : null,
+                        ownerId: typeof workstream?.ownerId === 'string' ? workstream.ownerId.trim() : null,
+                        createdAt: String(workstream?.createdAt || '').trim(),
+                        updatedAt: String(workstream?.updatedAt || workstream?.createdAt || '').trim(),
+                        order: Number.isFinite(Number(workstream?.order)) ? Math.floor(Number(workstream.order)) : null,
+                        isArchived: Boolean(workstream?.isArchived)
+                    }
+                }))
+                    .filter((change) => change.workstream.id.length > 0),
+                ...incomingAiProfiles
+                    .map((profile) => ({
+                    op: 'ai-profile-upsert',
+                    profile: {
+                        id: String(profile?.id || '').trim(),
+                        workspaceId: cloudWorkspaceId,
+                        profileToken: String(profile?.profileToken || '').trim(),
+                        name: String(profile?.name || '').trim(),
+                        username: String(profile?.username || '').trim(),
+                        icon: String(profile?.icon || 'Bot').trim() || 'Bot',
+                        color: String(profile?.color || '#8b5cf6').trim() || '#8b5cf6',
+                        surfaceType: normalizeIncomingAiProfileSurfaceType(profile?.surfaceType, {
+                            source: 'push.aiProfileUpsert',
+                            profileId: String(profile?.id || '').trim(),
+                            workspaceId: cloudWorkspaceId
+                        }),
+                        providerMetadata: profile?.providerMetadata && typeof profile.providerMetadata === 'object' && !Array.isArray(profile.providerMetadata)
+                            ? profile.providerMetadata
+                            : null,
+                        createdAt: String(profile?.createdAt || '').trim(),
+                        updatedAt: String(profile?.updatedAt || profile?.createdAt || '').trim(),
+                        lastActiveAt: typeof profile?.lastActiveAt === 'string' && profile.lastActiveAt.trim().length > 0
+                            ? profile.lastActiveAt.trim()
+                            : null
+                    }
+                }))
+                    .filter((change) => change.profile.id.length > 0),
+                ...incomingDocuments
+                    .map((doc) => ({
+                    op: 'document-upsert',
+                    path: String(doc?.path || '').trim(),
+                    updatedAt: String(doc?.updatedAt || '').trim(),
+                    content: typeof doc?.content === 'string' ? doc.content : '',
+                    assetId: typeof doc?.assetId === 'string' ? doc.assetId.trim() : undefined,
+                    documentId: typeof doc?.documentId === 'string' ? doc.documentId.trim() : null,
+                    referenceNumber: Number.isFinite(Number(doc?.referenceNumber)) ? Math.max(1, Math.floor(Number(doc.referenceNumber))) : null,
+                    version: Number.isFinite(Number(doc?.version)) ? Math.max(1, Math.floor(Number(doc.version))) : null,
+                    taskId: typeof doc?.taskId === 'string' ? doc.taskId.trim() : null,
+                    logicalName: typeof doc?.logicalName === 'string' ? doc.logicalName.trim() : null,
+                    caption: typeof doc?.caption === 'string' ? doc.caption.trim() : null,
+                    originalFilename: typeof doc?.originalFilename === 'string' ? doc.originalFilename.trim() : null,
+                    linkRole: (doc?.linkRole === 'reference' ? 'reference' : 'attachment')
+                }))
+                    .filter((doc) => doc.path.length > 0),
+                ...incomingAssets
+                    .map((asset) => ({
+                    op: 'asset-upsert',
+                    path: String(asset?.path || '').trim(),
+                    updatedAt: String(asset?.updatedAt || '').trim(),
+                    contentBase64: typeof asset?.contentBase64 === 'string' ? asset.contentBase64 : '',
+                    assetId: typeof asset?.assetId === 'string' ? asset.assetId.trim() : undefined,
+                    kind: asset?.kind === 'image' ? 'image' : 'file',
+                    mimeType: typeof asset?.mimeType === 'string' ? asset.mimeType.trim() : 'application/octet-stream',
+                    referenceNumber: Number.isFinite(Number(asset?.referenceNumber)) ? Math.max(1, Math.floor(Number(asset.referenceNumber))) : null,
+                    taskId: typeof asset?.taskId === 'string' ? asset.taskId.trim() : null,
+                    logicalName: typeof asset?.logicalName === 'string' ? asset.logicalName.trim() : null,
+                    caption: typeof asset?.caption === 'string' ? asset.caption.trim() : null,
+                    originalFilename: typeof asset?.originalFilename === 'string' ? asset.originalFilename.trim() : null,
+                    linkRole: asset?.linkRole === 'reference'
+                        ? 'reference'
+                        : asset?.kind === 'image'
+                            ? 'image'
+                            : 'attachment'
+                }))
+                    .filter((asset) => asset.path.length > 0 && asset.contentBase64.length > 0),
+                ...incomingDocumentReviewSessions
+                    .map((session) => ({
+                    op: 'document-review-session-upsert',
+                    session: {
+                        id: String(session?.id || '').trim(),
+                        assetId: String(session?.assetId || '').trim(),
+                        documentId: typeof session?.documentId === 'string' ? session.documentId.trim() : null,
+                        documentVersion: Number.isFinite(Number(session?.documentVersion)) ? Math.max(1, Math.floor(Number(session.documentVersion))) : null,
+                        title: typeof session?.title === 'string' ? session.title.trim() : null,
+                        status: session?.status === 'resolved' ? 'resolved' : 'open',
+                        comments: [],
+                        createdByActorId: typeof session?.createdByActorId === 'string' ? session.createdByActorId.trim() : null,
+                        updatedByActorId: typeof session?.updatedByActorId === 'string' ? session.updatedByActorId.trim() : null,
+                        createdAt: String(session?.createdAt || '').trim(),
+                        updatedAt: String(session?.updatedAt || session?.createdAt || '').trim(),
+                        deletedAt: typeof session?.deletedAt === 'string' && session.deletedAt.trim().length > 0 ? session.deletedAt.trim() : null
+                    }
+                }))
+                    .filter((change) => change.session.id.length > 0 && change.session.assetId.length > 0),
+                ...(incomingDocumentReviewComments.length > 0
+                    ? incomingDocumentReviewComments
+                    : incomingDocumentReviewSessions.flatMap((session) => {
+                        const sessionId = String(session?.id || '').trim();
+                        const comments = Array.isArray(session?.comments) ? session.comments : [];
+                        return comments.map((comment) => ({ sessionId, comment }));
+                    }))
+                    .map((entry) => {
+                    const isLegacyNested = 'comment' in entry;
+                    const comment = (isLegacyNested ? entry.comment : entry) && typeof (isLegacyNested ? entry.comment : entry) === 'object'
+                        ? (isLegacyNested ? entry.comment : entry)
+                        : null;
+                    const sessionId = isLegacyNested
+                        ? String(entry.sessionId || '').trim()
+                        : String(comment?.sessionId || '').trim();
+                    return {
+                        op: 'document-review-comment-upsert',
+                        comment: {
+                            id: String(comment?.id || '').trim(),
+                            sessionId,
+                            body: typeof comment?.body === 'string' ? comment.body : '',
+                            anchor: comment?.anchor ?? null,
+                            order: Number.isFinite(Number(comment?.order)) ? Math.max(0, Math.floor(Number(comment?.order))) : 0,
+                            authorActorId: typeof comment?.authorActorId === 'string' ? comment.authorActorId.trim() : null,
+                            createdAt: String(comment?.createdAt || '').trim(),
+                            updatedAt: String(comment?.updatedAt || comment?.createdAt || '').trim(),
+                            deletedAt: typeof comment?.deletedAt === 'string' && comment.deletedAt.trim().length > 0 ? comment.deletedAt.trim() : null,
+                        }
+                    };
+                })
+                    .filter((change) => change.comment.id.length > 0 && change.comment.sessionId.length > 0),
+                ...incomingAnnotatedAttachmentSessions
+                    .map((session) => ({
+                    op: 'annotated-attachment-session-upsert',
+                    session: {
+                        id: String(session?.id || '').trim(),
+                        workspaceId: cloudWorkspaceId,
+                        taskId: typeof session?.taskId === 'string' ? session.taskId.trim() : '',
+                        baseImageAssetId: typeof session?.baseImageAssetId === 'string' ? session.baseImageAssetId.trim() : '',
+                        title: typeof session?.title === 'string' ? session.title.trim() : null,
+                        globalInstruction: typeof session?.globalInstruction === 'string' ? session.globalInstruction.trim() : null,
+                        annotations: Array.isArray(session?.annotations) ? session.annotations : [],
+                        createdByActorId: typeof session?.createdByActorId === 'string' ? session.createdByActorId.trim() : null,
+                        updatedByActorId: typeof session?.updatedByActorId === 'string' ? session.updatedByActorId.trim() : null,
+                        createdAt: String(session?.createdAt || '').trim(),
+                        updatedAt: String(session?.updatedAt || session?.createdAt || '').trim(),
+                        deletedAt: typeof session?.deletedAt === 'string' && session.deletedAt.trim().length > 0 ? session.deletedAt.trim() : null
+                    }
+                }))
+                    .filter((change) => (change.session.id.length > 0
+                    && change.session.workspaceId.length > 0
+                    && change.session.baseImageAssetId.length > 0)),
+                ...tasks.map((task) => ({ op: 'upsert', archived: false, task })),
+                ...archived.map((task) => ({ op: 'upsert', archived: true, task }))
+            ];
+            const { result } = await dispatchWorkspaceSyncChanges(cloudWorkspaceId, bootstrapChanges);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: true,
+                workspaceId: cloudWorkspaceId,
+                result
+            }));
+            auditAuthAction(req, 'sync-workspace-bootstrap-success', {
+                workspaceId: cloudWorkspaceId,
+                taskCount: tasks.length,
+                archivedCount: archived.length,
+                taxonomyCount: incomingTaxonomies?.length ?? 0,
+                aiProfileCount: incomingAiProfiles.length,
+                documentCount: incomingDocuments.length,
+                documentReviewSessionCount: incomingDocumentReviewSessions.length,
+                documentReviewCommentCount: incomingDocumentReviewComments.length,
+                annotatedAttachmentSessionCount: incomingAnnotatedAttachmentSessions.length,
+                assetCount: incomingAssets.length
+            });
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            auditAuthAction(req, 'sync-workspace-bootstrap-failed', {
+                workspaceId: cloudWorkspaceId,
+                code: error?.code || null,
+                statusCode,
+                details: error?.details || null
+            });
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: String(error?.message || 'Failed to apply workspace snapshot'),
+                code: error?.code,
+                details: error?.details || undefined
+            }));
+        }
+    });
+    // GET /api/taskforce/sync/workspace/documents - Snapshot markdown documents only.
+    // Binary image/file assets travel through the sibling /assets snapshot and asset-* sync ops.
+    addRoute('GET', '/api/taskforce/sync/workspace/documents', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (authConfig?.runtimeMode === 'cloud') {
+            const access = resolveRequestAccess(req, authConfig);
+            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+                return;
+            }
+        }
+        const workspaceId = requestWorkspaceId(req) || 'default';
+        const basePath = core.getPaths().basePath;
+        const documents = await listWorkspaceSyncDocumentsSnapshot(basePath, workspaceId);
+        const fingerprint = JSON.stringify(documents.map((doc) => [
+            doc.path,
+            doc.updatedAt,
+            doc.content.length,
+            doc.assetId || '',
+            doc.documentId || '',
+            String(doc.version ?? ''),
+            doc.taskId || '',
+            doc.linkRole || ''
+        ].join(':')));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            documents,
+            fingerprint
+        }));
+    });
+    // GET /api/taskforce/sync/workspace/ai-profiles - Snapshot workspace AI profiles for local->cloud sync.
+    addRoute('GET', '/api/taskforce/sync/workspace/ai-profiles', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (authConfig?.runtimeMode === 'cloud') {
+            const access = resolveRequestAccess(req, authConfig);
+            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+                return;
+            }
+        }
+        const workspaceId = requestWorkspaceId(req) || 'default';
+        const aiProfiles = core.listAiProfiles(workspaceId);
+        const fingerprint = JSON.stringify(aiProfiles.map((profile) => [
+            profile.id,
+            profile.updatedAt,
+            profile.name,
+            profile.username,
+            profile.profileToken,
+            profile.surfaceType ?? ''
+        ].join(':')));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            aiProfiles,
+            fingerprint
+        }));
+    });
+    // GET /api/taskforce/sync/workspace/document-reviews - Snapshot document review sessions for local->cloud sync.
+    addRoute('GET', '/api/taskforce/sync/workspace/document-reviews', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (authConfig?.runtimeMode === 'cloud') {
+            const access = resolveRequestAccess(req, authConfig);
+            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+                return;
+            }
+        }
+        const workspaceId = requestWorkspaceId(req) || 'default';
+        const sessions = listWorkspaceSyncDocumentReviewSessionsSnapshot(workspaceId);
+        const comments = listWorkspaceSyncDocumentReviewCommentsSnapshot(workspaceId);
+        const fingerprint = JSON.stringify([
+            ...sessions.map((session) => [
+                'session',
+                session.id,
+                session.updatedAt,
+                session.status,
+                session.comments.length
+            ].join(':')),
+            ...comments.map((comment) => [
+                'comment',
+                comment.id,
+                comment.sessionId,
+                comment.updatedAt,
+                comment.deletedAt || ''
+            ].join(':'))
+        ]);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            sessions,
+            comments,
+            fingerprint
+        }));
+    });
+    // GET /api/taskforce/sync/workspace/annotated-attachments - Snapshot Image Notes sessions for local->cloud sync.
+    addRoute('GET', '/api/taskforce/sync/workspace/annotated-attachments', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (authConfig?.runtimeMode === 'cloud') {
+            const access = resolveRequestAccess(req, authConfig);
+            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+                return;
+            }
+        }
+        const workspaceId = requestWorkspaceId(req) || 'default';
+        const sessions = listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(workspaceId);
+        const fingerprint = JSON.stringify(sessions.map((session) => [
+            session.id,
+            session.updatedAt,
+            session.taskId,
+            session.baseImageAssetId,
+            session.annotations.length,
+            session.deletedAt || ''
+        ].join(':')));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            sessions,
+            fingerprint
+        }));
+    });
+    // GET /api/taskforce/sync/workspace/assets - Snapshot non-markdown local assets.
+    // Markdown remains on the /documents snapshot so document encryption/version semantics stay isolated.
+    addRoute('GET', '/api/taskforce/sync/workspace/assets', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (authConfig?.runtimeMode === 'cloud') {
+            const access = resolveRequestAccess(req, authConfig);
+            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+                return;
+            }
+        }
+        const workspaceId = requestWorkspaceId(req) || 'default';
+        const basePath = core.getPaths().basePath;
+        const assets = await listWorkspaceSyncBinaryAssetsSnapshot(basePath, workspaceId);
+        const fingerprint = JSON.stringify(assets.map((asset) => [
+            asset.path,
+            asset.updatedAt,
+            asset.contentBase64.length,
+            asset.assetId || '',
+            asset.kind,
+            asset.mimeType,
+            asset.taskId || '',
+            asset.originalFilename || '',
+            asset.linkRole || ''
+        ].join(':')));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            assets,
+            fingerprint
+        }));
+    });
+    // GET /api/taskforce/sync/workspace/pull - Incremental workspace task deltas with cursor paging
+    addRoute('GET', '/api/taskforce/sync/workspace/pull', async (req, res) => {
+        const authConfig = context.authConfig;
+        if (!authConfig || !authConfig.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Sync is unavailable when auth is disabled.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+            auditAuthAction(req, 'sync-workspace-pull-unauthorized', {});
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const url = new URL(req.url || '/api/taskforce/sync/workspace/pull', 'http://localhost');
+        const requestedWorkspaceId = String(url.searchParams.get('workspaceId') || '').trim();
+        if (!requestedWorkspaceId) {
+            auditAuthAction(req, 'sync-workspace-pull-missing-workspace', { code: 'WORKSPACE_ID_REQUIRED' });
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'workspaceId is required.',
+                code: 'WORKSPACE_ID_REQUIRED',
+                workspaceId: null
+            }));
+            return;
+        }
+        const allowed = core.listUserWorkspaces(access.userId).find((workspace) => workspace.id === requestedWorkspaceId);
+        if (!allowed) {
+            auditAuthAction(req, 'sync-workspace-pull-forbidden', {
+                requestedWorkspaceId
+            });
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'You do not have access to this workspace.',
+                code: 'WORKSPACE_ACCESS_DENIED',
+                workspaceId: requestedWorkspaceId
+            }));
+            return;
+        }
+        const targetWorkspaceId = requestedWorkspaceId;
+        const cursor = decodeWorkspaceSyncCursor(url.searchParams.get('cursor'));
+        const requestedLimit = Number.parseInt(String(url.searchParams.get('limit') || ''), 10);
+        const pageSize = Number.isFinite(requestedLimit) && requestedLimit > 0
+            ? Math.max(1, Math.min(500, Math.floor(requestedLimit)))
+            : 200;
+        // Use watermark-indexed queries to avoid full table scans (Finding 12).
+        // Fetch up to pageSize * 2 tasks/deletes from DB since the cursor, then merge with
+        // small in-memory collections (taxonomy, documents) before slicing to pageSize.
+        const syncCursor = cursor ? { watermark: cursor.u, id: cursor.id } : null;
+        const dbFetchLimit = pageSize * 2 + 10;
+        const taskRows = core.listTasksForSync(targetWorkspaceId, syncCursor, dbFetchLimit);
+        const upsertEntries = taskRows
+            .map((entry) => {
+            const watermark = String(entry.task?.updatedAt || entry.task?.createdAt || '').trim();
+            const taskId = String(entry.task?.id || '').trim();
+            return {
+                kind: 'upsert',
+                watermark,
+                sortId: taskId,
+                task: entry.task,
+                archived: Boolean(entry.archived)
+            };
+        })
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sortId.length > 0);
+        const rawDeleteEntries = core.listWorkspaceSyncDeletesSince(targetWorkspaceId, syncCursor, dbFetchLimit);
+        const deleteEntries = rawDeleteEntries
+            .map((entry) => ({
+            kind: 'delete',
+            watermark: String(entry.deletedAt || '').trim(),
+            sortId: String(entry.taskId || '').trim(),
+            taskId: String(entry.taskId || '').trim()
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sortId.length > 0);
+        const taxonomySnapshot = core.getTaxonomiesSyncSnapshot(targetWorkspaceId);
+        const taxonomyEntries = (taxonomySnapshot
+            && Array.isArray(taxonomySnapshot.taxonomies)
+            && Number.isFinite(Date.parse(String(taxonomySnapshot.updatedAt || '').trim())))
+            ? [{
+                    kind: 'taxonomy',
+                    watermark: String(taxonomySnapshot.updatedAt || '').trim(),
+                    sortId: '__taxonomy_config__',
+                    taxonomies: taxonomySnapshot.taxonomies,
+                    taxonomyState: taxonomySnapshot.taxonomyState || null
+                }]
+            : [];
+        const initiativeEntries = core.listInitiatives(targetWorkspaceId)
+            .map((initiative) => ({
+            kind: 'initiative',
+            watermark: String(initiative.updatedAt || initiative.createdAt || '').trim(),
+            sortId: `initiative:${String(initiative.id || '').trim()}`,
+            initiative
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.initiative.id.length > 0);
+        const workstreamEntries = core.listWorkstreams(targetWorkspaceId)
+            .map((workstream) => ({
+            kind: 'workstream',
+            watermark: String(workstream.updatedAt || workstream.createdAt || '').trim(),
+            sortId: `workstream:${String(workstream.id || '').trim()}`,
+            workstream
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.workstream.id.length > 0);
+        const aiProfileEntries = core.listAiProfiles(targetWorkspaceId)
+            .map((profile) => ({
+            kind: 'ai-profile',
+            watermark: String(profile.updatedAt || profile.createdAt || '').trim(),
+            sortId: `ai-profile:${String(profile.id || '').trim()}`,
+            profile
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sortId.length > 0);
+        const documentEntries = (await listWorkspaceSyncDocumentsSnapshot(core.getPaths().basePath, targetWorkspaceId))
+            .map((doc) => ({
+            kind: 'document',
+            watermark: String(doc.updatedAt || '').trim(),
+            sortId: `doc:${String(doc.path || '').trim()}`,
+            path: String(doc.path || '').trim(),
+            content: String(doc.content || ''),
+            assetId: doc.assetId,
+            documentId: doc.documentId,
+            referenceNumber: doc.referenceNumber,
+            version: doc.version,
+            taskId: doc.taskId,
+            logicalName: doc.logicalName,
+            caption: doc.caption,
+            originalFilename: doc.originalFilename,
+            linkRole: doc.linkRole
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
+        const documentDeleteEntries = listWorkspaceSyncDocumentDeletesSnapshot(targetWorkspaceId)
+            .map((doc) => ({
+            kind: 'document-delete',
+            watermark: String(doc.deletedAt || '').trim(),
+            sortId: `doc-delete:${String(doc.path || '').trim()}:${String(doc.assetId || '').trim()}`,
+            path: String(doc.path || '').trim(),
+            assetId: typeof doc.assetId === 'string' && doc.assetId.trim().length > 0 ? doc.assetId.trim() : undefined
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
+        const documentReviewSessionEntries = listWorkspaceSyncDocumentReviewSessionsSnapshot(targetWorkspaceId)
+            .filter((session) => !session.deletedAt)
+            .map((session) => ({
+            kind: 'document-review-session',
+            watermark: String(session.updatedAt || session.createdAt || '').trim(),
+            sortId: `document-review-session:${String(session.id || '').trim()}`,
+            session
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.session.id.length > 0 && entry.session.assetId.length > 0);
+        const documentReviewSessionDeleteEntries = listWorkspaceSyncDocumentReviewSessionsSnapshot(targetWorkspaceId)
+            .filter((session) => typeof session.deletedAt === 'string' && session.deletedAt.trim().length > 0)
+            .map((session) => ({
+            kind: 'document-review-session-delete',
+            watermark: String(session.deletedAt || session.updatedAt || '').trim(),
+            sortId: `document-review-session-delete:${String(session.id || '').trim()}`,
+            sessionId: String(session.id || '').trim()
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sessionId.length > 0);
+        const documentReviewCommentEntries = listWorkspaceSyncDocumentReviewCommentsSnapshot(targetWorkspaceId)
+            .filter((comment) => !comment.deletedAt)
+            .map((comment) => ({
+            kind: 'document-review-comment',
+            watermark: String(comment.updatedAt || comment.createdAt || '').trim(),
+            sortId: `document-review-comment:${String(comment.id || '').trim()}`,
+            comment
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.comment.id.length > 0 && entry.comment.sessionId.length > 0);
+        const documentReviewCommentDeleteEntries = listWorkspaceSyncDocumentReviewCommentsSnapshot(targetWorkspaceId)
+            .filter((comment) => typeof comment.deletedAt === 'string' && comment.deletedAt.trim().length > 0)
+            .map((comment) => ({
+            kind: 'document-review-comment-delete',
+            watermark: String(comment.deletedAt || comment.updatedAt || '').trim(),
+            sortId: `document-review-comment-delete:${String(comment.id || '').trim()}`,
+            commentId: String(comment.id || '').trim()
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.commentId.length > 0);
+        const annotatedAttachmentSessionEntries = listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(targetWorkspaceId)
+            .filter((session) => !session.deletedAt)
+            .map((session) => ({
+            kind: 'annotated-attachment-session',
+            watermark: String(session.updatedAt || session.createdAt || '').trim(),
+            sortId: `annotated-attachment-session:${String(session.id || '').trim()}`,
+            session
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.session.id.length > 0 && entry.session.baseImageAssetId.length > 0);
+        const annotatedAttachmentSessionDeleteEntries = listWorkspaceSyncAnnotatedAttachmentSessionsSnapshot(targetWorkspaceId)
+            .filter((session) => typeof session.deletedAt === 'string' && session.deletedAt.trim().length > 0)
+            .map((session) => ({
+            kind: 'annotated-attachment-session-delete',
+            watermark: String(session.deletedAt || session.updatedAt || '').trim(),
+            sortId: `annotated-attachment-session-delete:${String(session.id || '').trim()}`,
+            sessionId: String(session.id || '').trim()
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.sessionId.length > 0);
+        const assetEntries = (await listWorkspaceSyncBinaryAssetsSnapshot(core.getPaths().basePath, targetWorkspaceId))
+            .map((asset) => ({
+            kind: 'asset',
+            watermark: String(asset.updatedAt || '').trim(),
+            sortId: `asset:${String(asset.path || '').trim()}`,
+            path: String(asset.path || '').trim(),
+            contentBase64: String(asset.contentBase64 || ''),
+            assetId: asset.assetId,
+            kindValue: asset.kind,
+            mimeType: asset.mimeType,
+            referenceNumber: asset.referenceNumber,
+            taskId: asset.taskId,
+            logicalName: asset.logicalName,
+            caption: asset.caption,
+            originalFilename: asset.originalFilename,
+            linkRole: asset.linkRole
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0 && entry.contentBase64.length > 0);
+        const assetDeleteEntries = listWorkspaceSyncBinaryAssetDeletesSnapshot(targetWorkspaceId)
+            .map((asset) => ({
+            kind: 'asset-delete',
+            watermark: String(asset.deletedAt || '').trim(),
+            sortId: `asset-delete:${String(asset.path || '').trim()}:${String(asset.assetId || '').trim()}`,
+            path: String(asset.path || '').trim(),
+            assetId: typeof asset.assetId === 'string' && asset.assetId.trim().length > 0 ? asset.assetId.trim() : undefined
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
+        const all = [
+            ...upsertEntries,
+            ...deleteEntries,
+            ...taxonomyEntries,
+            ...initiativeEntries,
+            ...workstreamEntries,
+            ...aiProfileEntries,
+            ...documentEntries,
+            ...documentDeleteEntries,
+            ...documentReviewSessionEntries,
+            ...documentReviewSessionDeleteEntries,
+            ...documentReviewCommentEntries,
+            ...documentReviewCommentDeleteEntries,
+            ...annotatedAttachmentSessionEntries,
+            ...annotatedAttachmentSessionDeleteEntries,
+            ...assetEntries,
+            ...assetDeleteEntries
+        ];
+        const afterCursor = all.filter((entry) => {
+            if (!cursor)
+                return true;
+            const watermark = entry.watermark;
+            const sortId = entry.sortId;
+            if (watermark > cursor.u)
+                return true;
+            if (watermark < cursor.u)
+                return false;
+            return sortId > cursor.id;
+        });
+        afterCursor.sort((a, b) => {
+            if (a.watermark !== b.watermark)
+                return a.watermark.localeCompare(b.watermark);
+            return String(a.sortId || '').localeCompare(String(b.sortId || ''));
+        });
+        const page = afterCursor.slice(0, pageSize);
+        const hasMore = afterCursor.length > pageSize;
+        const last = page.length > 0 ? page[page.length - 1] : null;
+        const nextCursor = encodeWorkspaceSyncCursor(last
+            ? { u: last.watermark, id: String(last.sortId || '') }
+            : cursor);
+        const workspaceMembers = core.listWorkspaceUsers(targetWorkspaceId).map((member) => ({
+            userId: member.userId,
+            workspaceId: targetWorkspaceId,
+            email: member.email,
+            displayName: member.displayName || null,
+            role: member.role,
+            permissionMode: member.permissionMode,
+            betaAccess: member.betaAccess,
+            status: member.status,
+            disabled: member.disabled,
+            createdAt: member.createdAt || null,
+            updatedAt: member.updatedAt || null,
+            emailVerifiedAt: member.emailVerifiedAt || null
+        }));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            workspaceId: targetWorkspaceId,
+            workspaceMembers,
+            changes: page.map((entry) => (entry.kind === 'delete'
+                ? {
+                    op: 'delete',
+                    taskId: entry.taskId,
+                    deletedAt: entry.watermark,
+                    watermark: entry.watermark
+                }
+                : entry.kind === 'taxonomy'
+                    ? {
+                        op: 'taxonomy-upsert',
+                        taxonomies: entry.taxonomies,
+                        taxonomyState: entry.taxonomyState,
+                        watermark: entry.watermark
+                    }
+                    : entry.kind === 'initiative'
+                        ? {
+                            op: 'initiative-upsert',
+                            initiative: entry.initiative,
+                            updatedAt: entry.watermark,
+                            watermark: entry.watermark
+                        }
+                        : entry.kind === 'workstream'
+                            ? {
+                                op: 'workstream-upsert',
+                                workstream: entry.workstream,
+                                updatedAt: entry.watermark,
+                                watermark: entry.watermark
+                            }
+                            : entry.kind === 'ai-profile'
+                                ? {
+                                    op: 'ai-profile-upsert',
+                                    profile: entry.profile,
+                                    updatedAt: entry.watermark,
+                                    watermark: entry.watermark
+                                }
+                                : entry.kind === 'document-review-session'
+                                    ? {
+                                        op: 'document-review-session-upsert',
+                                        session: entry.session,
+                                        updatedAt: entry.watermark,
+                                        watermark: entry.watermark
+                                    }
+                                    : entry.kind === 'document-review-session-delete'
+                                        ? {
+                                            op: 'document-review-session-delete',
+                                            sessionId: entry.sessionId,
+                                            deletedAt: entry.watermark,
+                                            watermark: entry.watermark
+                                        }
+                                        : entry.kind === 'document-review-comment'
+                                            ? {
+                                                op: 'document-review-comment-upsert',
+                                                comment: entry.comment,
+                                                updatedAt: entry.watermark,
+                                                watermark: entry.watermark
+                                            }
+                                            : entry.kind === 'document-review-comment-delete'
+                                                ? {
+                                                    op: 'document-review-comment-delete',
+                                                    commentId: entry.commentId,
+                                                    deletedAt: entry.watermark,
+                                                    watermark: entry.watermark
+                                                }
+                                                : entry.kind === 'annotated-attachment-session'
+                                                    ? {
+                                                        op: 'annotated-attachment-session-upsert',
+                                                        session: entry.session,
+                                                        updatedAt: entry.watermark,
+                                                        watermark: entry.watermark
+                                                    }
+                                                    : entry.kind === 'annotated-attachment-session-delete'
+                                                        ? {
+                                                            op: 'annotated-attachment-session-delete',
+                                                            sessionId: entry.sessionId,
+                                                            deletedAt: entry.watermark,
+                                                            watermark: entry.watermark
+                                                        }
+                                                        // Keep markdown and binary assets on separate ops so the protocol stays explicit:
+                                                        // document-* carries markdown content + document identity, asset-* carries image/file bytes.
+                                                        : entry.kind === 'document'
+                                                            ? {
+                                                                op: 'document-upsert',
+                                                                path: entry.path,
+                                                                updatedAt: entry.watermark,
+                                                                content: entry.content,
+                                                                assetId: entry.assetId,
+                                                                documentId: entry.documentId,
+                                                                referenceNumber: entry.referenceNumber,
+                                                                version: entry.version,
+                                                                taskId: entry.taskId,
+                                                                logicalName: entry.logicalName,
+                                                                caption: entry.caption,
+                                                                originalFilename: entry.originalFilename,
+                                                                linkRole: entry.linkRole,
+                                                                watermark: entry.watermark
+                                                            }
+                                                            : entry.kind === 'document-delete'
+                                                                ? {
+                                                                    op: 'document-delete',
+                                                                    path: entry.path,
+                                                                    assetId: entry.assetId,
+                                                                    deletedAt: entry.watermark,
+                                                                    watermark: entry.watermark
+                                                                }
+                                                                : entry.kind === 'asset'
+                                                                    ? {
+                                                                        op: 'asset-upsert',
+                                                                        path: entry.path,
+                                                                        updatedAt: entry.watermark,
+                                                                        contentBase64: entry.contentBase64,
+                                                                        assetId: entry.assetId,
+                                                                        kind: entry.kindValue,
+                                                                        mimeType: entry.mimeType,
+                                                                        referenceNumber: entry.referenceNumber,
+                                                                        taskId: entry.taskId,
+                                                                        logicalName: entry.logicalName,
+                                                                        caption: entry.caption,
+                                                                        originalFilename: entry.originalFilename,
+                                                                        linkRole: entry.linkRole,
+                                                                        watermark: entry.watermark
+                                                                    }
+                                                                    : entry.kind === 'asset-delete'
+                                                                        ? {
+                                                                            op: 'asset-delete',
+                                                                            path: entry.path,
+                                                                            assetId: entry.assetId,
+                                                                            deletedAt: entry.watermark,
+                                                                            watermark: entry.watermark
+                                                                        }
+                                                                        : {
+                                                                            op: 'upsert',
+                                                                            task: entry.task,
+                                                                            archived: Boolean(entry.archived),
+                                                                            watermark: entry.watermark
+                                                                        })),
+            nextCursor,
+            hasMore
+        }));
+        auditAuthAction(req, 'sync-workspace-pull-success', {
+            workspaceId: targetWorkspaceId,
+            returnedChanges: page.length,
+            hasMore
+        });
+    });
+    // POST /api/taskforce/sync/workspace/apply-local - Apply pulled cloud deltas into local workspace store
+    addRoute('POST', '/api/taskforce/sync/workspace/apply-local', async (req, res) => {
+        const startedAtMs = Date.now();
+        const authConfig = context.authConfig;
+        if (authConfig?.runtimeMode === 'cloud') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Local apply endpoint is only available in local runtime.' }));
+            return;
+        }
+        const body = await parseJsonBody(req, 50 * 1024 * 1024);
+        const bodyWorkspaceId = String(body?.workspaceId || '').trim();
+        const headerWorkspaceId = String(Array.isArray(req.headers['x-taskforce-workspace-id'])
+            ? req.headers['x-taskforce-workspace-id'][0]
+            : req.headers['x-taskforce-workspace-id'] || '').trim();
+        let workspaceId = bodyWorkspaceId || headerWorkspaceId || requestWorkspaceId(req);
+        if (authConfig?.enabled) {
+            const access = resolveRequestAccess(req, authConfig);
+            if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+                auditAuthAction(req, 'sync-workspace-apply-unauthorized', {});
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+                return;
+            }
+            if (workspaceId && workspaceId !== 'default' && workspaceId !== 'null') {
+                const allowed = core.listUserWorkspaces(access.userId).find((workspace) => workspace.id === workspaceId);
+                if (!allowed) {
+                    auditAuthAction(req, 'sync-workspace-apply-forbidden', {
+                        requestedWorkspaceId: workspaceId
+                    });
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        success: false,
+                        error: 'You do not have access to this workspace.',
+                        code: 'WORKSPACE_ACCESS_DENIED',
+                        workspaceId
+                    }));
+                    return;
+                }
+            }
+            else {
+                const accessWorkspaceId = String(access.workspaceId || '').trim();
+                if (accessWorkspaceId && accessWorkspaceId !== 'default') {
+                    workspaceId = accessWorkspaceId;
+                }
+            }
+        }
+        if (!workspaceId || workspaceId === 'default' || workspaceId === 'null') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'Workspace ID required.',
+                code: 'WORKSPACE_ID_REQUIRED'
+            }));
+            return;
+        }
+        const incomingChanges = Array.isArray(body?.changes) ? body.changes : [];
+        const workspaceMembers = Array.isArray(body?.workspaceMembers)
+            ? body.workspaceMembers
+                .map((entry) => normalizeWorkspaceMemberSyncSnapshot(workspaceId, entry && typeof entry === 'object' ? entry : null))
+                .filter((entry) => Boolean(entry))
+            : undefined;
+        const allowReferenceNumberReassignment = body?.repair === true;
+        try {
+            const { result, emittedEventIds } = await dispatchWorkspaceSyncChanges(workspaceId, incomingChanges, {
+                allowReferenceNumberReassignment,
+                ...(Array.isArray(workspaceMembers) ? { workspaceMembers } : {})
+            });
+            const durationMs = Date.now() - startedAtMs;
+            core.recordSyncEvent(workspaceId, {
+                eventType: 'apply',
+                status: 'success',
+                changeCount: incomingChanges.length,
+                requestMs: durationMs
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: true,
+                workspaceId,
+                result,
+                emittedEventIds,
+                durationMs
+            }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            const durationMs = Date.now() - startedAtMs;
+            core.recordSyncEvent(workspaceId, {
+                eventType: 'apply',
+                status: 'error',
+                statusCode,
+                errorMessage: String(error?.message || 'Failed to apply local workspace deltas'),
+                changeCount: incomingChanges.length,
+                requestMs: durationMs
+            });
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: String(error?.message || 'Failed to apply local workspace deltas'),
+                code: error?.code,
+                details: error?.details || undefined,
+                durationMs
+            }));
+        }
+    });
+    // POST /api/taskforce/sync/workspace/push - Incremental workspace deltas from local to cloud
+    addRoute('POST', '/api/taskforce/sync/workspace/push', async (req, res) => {
+        const startedAtMs = Date.now();
+        const authConfig = context.authConfig;
+        if (!authConfig || !authConfig.enabled) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Sync is unavailable when auth is disabled.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        if (!access.authenticated || !access.userId || access.userId === 'anonymous') {
+            auditAuthAction(req, 'sync-workspace-push-unauthorized', {});
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req, 50 * 1024 * 1024);
+        const requestedWorkspaceId = String(body?.workspaceId || '').trim();
+        if (!requestedWorkspaceId) {
+            auditAuthAction(req, 'sync-workspace-push-missing-workspace', { code: 'WORKSPACE_ID_REQUIRED' });
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'workspaceId is required.',
+                code: 'WORKSPACE_ID_REQUIRED',
+                workspaceId: null,
+                durationMs: Date.now() - startedAtMs
+            }));
+            return;
+        }
+        const allowed = core.listUserWorkspaces(access.userId).find((workspace) => workspace.id === requestedWorkspaceId);
+        if (!allowed) {
+            auditAuthAction(req, 'sync-workspace-push-forbidden', {
+                requestedWorkspaceId
+            });
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'You do not have access to this workspace.',
+                code: 'WORKSPACE_ACCESS_DENIED',
+                workspaceId: requestedWorkspaceId
+            }));
+            return;
+        }
+        const targetWorkspaceId = requestedWorkspaceId;
+        const idempotencyKey = String(body?.idempotencyKey || '').trim();
+        if (idempotencyKey) {
+            const replay = readPushIdempotency(targetWorkspaceId, idempotencyKey);
+            if (replay) {
+                auditAuthAction(req, 'sync-workspace-push-idempotent-replay', {
+                    workspaceId: targetWorkspaceId,
+                    idempotencyKey
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(replay);
+                return;
+            }
+        }
+        let incomingChanges = Array.isArray(body?.changes) ? body.changes : [];
+        const allowReferenceNumberReassignment = body?.repair === true;
+        // Decrypt asset and document content if TASKFORCE_SYNC_KEY is configured on this server.
+        // The local runtime encrypts content before pushing; the cloud must decrypt before writing to storage.
+        if (typeof process !== 'undefined' && process.env?.TASKFORCE_SYNC_KEY) {
+            const syncKey = process.env.TASKFORCE_SYNC_KEY;
+            const decryptedChanges = [];
+            for (const change of incomingChanges) {
+                if (change.op === 'asset-upsert' && typeof change.contentBase64 === 'string' && change.contentBase64.startsWith(ENCRYPTION_PREFIX)) {
+                    try {
+                        decryptedChanges.push({ ...change, contentBase64: await decryptDocument(change.contentBase64, syncKey) });
+                    }
+                    catch {
+                        decryptedChanges.push(change);
+                    }
+                }
+                else if (change.op === 'document-upsert' && typeof change.content === 'string' && change.content.startsWith(ENCRYPTION_PREFIX)) {
+                    try {
+                        decryptedChanges.push({ ...change, content: await decryptDocument(change.content, syncKey) });
+                    }
+                    catch {
+                        decryptedChanges.push(change);
+                    }
+                }
+                else {
+                    decryptedChanges.push(change);
+                }
+            }
+            incomingChanges = decryptedChanges;
+        }
+        try {
+            const { result, deleteCount, emittedEventIds } = await dispatchWorkspaceSyncChanges(targetWorkspaceId, incomingChanges, {
+                allowReferenceNumberReassignment
+            });
+            const durationMs = Date.now() - startedAtMs;
+            const payload = JSON.stringify({
+                success: true,
+                workspaceId: targetWorkspaceId,
+                idempotencyKey: idempotencyKey || null,
+                emittedEventIds,
+                result,
+                durationMs
+            });
+            if (idempotencyKey) {
+                writePushIdempotency(targetWorkspaceId, idempotencyKey, payload);
+            }
+            core.recordSyncEvent(targetWorkspaceId, {
+                eventType: 'push',
+                status: 'success',
+                changeCount: incomingChanges.length,
+                requestMs: durationMs
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(payload);
+            auditAuthAction(req, 'sync-workspace-push-success', {
+                workspaceId: targetWorkspaceId,
+                idempotencyKey: idempotencyKey || null,
+                changeCount: incomingChanges.length,
+                deleteCount: deleteCount,
+                durationMs
+            });
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            const durationMs = Date.now() - startedAtMs;
+            core.recordSyncEvent(targetWorkspaceId, {
+                eventType: 'push',
+                status: 'error',
+                statusCode,
+                errorMessage: String(error?.message || 'Failed to apply workspace deltas'),
+                changeCount: incomingChanges.length,
+                requestMs: durationMs
+            });
+            auditAuthAction(req, 'sync-workspace-push-failed', {
+                workspaceId: targetWorkspaceId,
+                code: error?.code || null,
+                statusCode,
+                details: error?.details || null,
+                durationMs
+            });
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: String(error?.message || 'Failed to apply workspace deltas'),
+                code: error?.code,
+                details: error?.details || undefined,
+                durationMs
+            }));
+        }
+    });
+    // GET /api/taskforce/sync/events - Query recent sync events (local runtime only)
+    addRoute('GET', '/api/taskforce/sync/events', async (req, res) => {
+        const authConfig = context.authConfig;
+        const access = authConfig?.enabled ? resolveRequestAccess(req, authConfig) : null;
+        if (access && (!access.authenticated || !access.userId || access.userId === 'anonymous')) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const url = new URL(req.url || '/', 'http://localhost');
+        const workspaceId = String(url.searchParams.get('workspace_id') || access?.workspaceId || '').trim() || 'default';
+        const limit = Math.min(500, Math.max(1, Number(url.searchParams.get('limit') || '100')));
+        const events = core.listSyncEvents(workspaceId, limit);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, events }));
+    });
+    // POST /api/taskforce/sync/events - Record a client-side sync event (pull results, handshake outcomes)
+    addRoute('POST', '/api/taskforce/sync/events', async (req, res) => {
+        const authConfig = context.authConfig;
+        const access = authConfig?.enabled ? resolveRequestAccess(req, authConfig) : null;
+        if (access && (!access.authenticated || !access.userId || access.userId === 'anonymous')) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const allowedEventTypes = ['pull', 'handshake', 'bootstrap', 'apply', 'push'];
+        const eventType = String(body?.eventType || '').trim().toLowerCase();
+        if (!allowedEventTypes.includes(eventType)) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Invalid eventType.' }));
+            return;
+        }
+        const workspaceId = String(body?.workspaceId || access?.workspaceId || '').trim() || 'default';
+        core.recordSyncEvent(workspaceId, {
+            eventType: eventType,
+            status: String(body?.status || '') === 'error' ? 'error' : 'success',
+            statusCode: typeof body?.statusCode === 'number' ? body.statusCode : undefined,
+            errorMessage: typeof body?.errorMessage === 'string' ? body.errorMessage.slice(0, 500) : undefined,
+            changeCount: typeof body?.changeCount === 'number' ? body.changeCount : undefined,
+            requestMs: typeof body?.requestMs === 'number' ? body.requestMs : undefined,
+            details: body?.details && typeof body.details === 'object' && !Array.isArray(body.details)
+                ? body.details
+                : undefined
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    });
+    // POST /api/taskforce/sync/workspace/repair-startup - Auto-repair missing asset/document
+    // metadata on workspace open. Only safe fixups: re-registers DB records for files that
+    // exist on disk but have no (or a stale deleted) metadata entry. Never deletes files.
+    // Called once by the sync orchestrator when the workspace becomes active.
+    addRoute('POST', '/api/taskforce/sync/workspace/repair-startup', async (req, res) => {
+        const authConfig = context.authConfig;
+        const access = authConfig?.enabled ? resolveRequestAccess(req, authConfig) : null;
+        if (access && (!access.authenticated || !access.userId || access.userId === 'anonymous')) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const workspaceId = String(body?.workspaceId || requestWorkspaceId(req) || '').trim() || 'default';
+        if (!workspaceAssetStore) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, applied: 0, skipped: 0, failed: 0, detail: 'Asset store unavailable.' }));
+            return;
+        }
+        const { basePath } = core.getPaths();
+        const result = applyWorkspaceRepair({
+            workspaceId,
+            basePath,
+            tasks: core.listTasks(workspaceId)?.tasks || [],
+            archivedTasks: core.listArchive(workspaceId)?.archived || [],
+            deletedTasks: core.listWorkspaceSyncDeletes(workspaceId) || [],
+            workspaceAssetStore,
+            upsertDocumentWatermark: (targetWorkspaceId, docPath, contentHash, updatedAt) => {
+                core.upsertDocumentWatermark(targetWorkspaceId, docPath, contentHash, updatedAt);
+            }
+        });
+        const applied = result.actionsApplied.filter((a) => a.status === 'applied').length;
+        const failed = result.actionsApplied.filter((a) => a.status === 'failed').length;
+        const skipped = result.actionsApplied.filter((a) => a.status === 'skipped').length;
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, applied, skipped, failed }));
+    });
+}