@taskforcehq/taskforce 0.3.168

package/dist/server/routes.sync.js

@@ -0,0 +1,1141 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import { parseJsonBody } from './routes.js';
+import { normalizeTaskDataRelativePath } from '../storage/objectStorageClient.js';
+import { resolveSessionCookieAttributesForRequest } from './auth.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');
+}
+export function registerSyncRoutes(deps) {
+    const { addRoute, core, context, auditAuthAction, resolveErrorStatusCode, requestWorkspaceId, resolveRequestAccess, isReservedWorkspaceId, createSessionTokenCookie } = deps;
+    const readPushIdempotency = (workspaceId, key) => {
+        if (typeof core.readPushIdempotency === 'function') {
+            return core.readPushIdempotency(workspaceId, key);
+        }
+        return null;
+    };
+    const writePushIdempotency = (workspaceId, key, payload) => {
+        if (typeof core.writePushIdempotency === 'function') {
+            core.writePushIdempotency(workspaceId, key, payload);
+        }
+    };
+    const recordSyncDiagnostic = (workspaceId, eventType, errorMessage, details) => {
+        try {
+            core.recordSyncEvent(workspaceId, {
+                eventType,
+                status: 'error',
+                errorMessage,
+                requestMs: 0
+            });
+        }
+        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 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 (normalized.startsWith('docs/'))
+            return normalized;
+        const normalizedTaskData = normalizeTaskDataRelativePath(normalized);
+        if (!normalizedTaskData || !isMarkdownPath(normalizedTaskData))
+            return null;
+        return normalizedTaskData;
+    };
+    const listWorkspaceSyncDocumentsSnapshot = (basePath, workspaceId = 'default') => {
+        const collectFiles = (dirPath, baseRelative, out) => {
+            if (!fs.existsSync(dirPath))
+                return;
+            let entries = [];
+            try {
+                entries = fs.readdirSync(dirPath, { withFileTypes: true });
+            }
+            catch (error) {
+                recordSyncDiagnostic(workspaceId, 'pull', 'Failed to read sync document directory.', {
+                    source: 'documents.collectFiles',
+                    dirPath,
+                    error: String(error?.message || error || '')
+                });
+                return;
+            }
+            for (const entry of entries) {
+                if (!entry || typeof entry.name !== 'string')
+                    continue;
+                const absPath = path.join(dirPath, entry.name);
+                const relPath = path.posix.join(baseRelative, entry.name);
+                if (entry.isDirectory()) {
+                    collectFiles(absPath, relPath, out);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                if (!isMarkdownPath(relPath))
+                    continue;
+                const normalized = normalizeWorkspaceSyncDocumentPath(relPath);
+                if (!normalized)
+                    continue;
+                out.push(normalized);
+            }
+        };
+        const candidatePaths = [];
+        collectFiles(path.join(basePath, '.taskforce', 'docs'), 'docs', candidatePaths);
+        collectFiles(path.join(basePath, '.taskforce', 'task-data'), 'task-data', candidatePaths);
+        const uniquePaths = Array.from(new Set(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) {
+            const absPath = path.resolve(path.join(basePath, '.taskforce'), relativePath);
+            const safeRoot = path.resolve(path.join(basePath, '.taskforce'));
+            if (absPath !== safeRoot && !absPath.startsWith(`${safeRoot}${path.sep}`))
+                continue;
+            try {
+                const stat = fs.statSync(absPath);
+                if (!stat.isFile())
+                    continue;
+                const cached = workspaceCache.get(relativePath);
+                if (cached
+                    && cached.size === stat.size
+                    && cached.mtimeMs === stat.mtimeMs
+                    && cached.ctimeMs === stat.ctimeMs) {
+                    docs.push({
+                        path: relativePath,
+                        updatedAt: cached.updatedAt,
+                        content: cached.content
+                    });
+                    continue;
+                }
+                const content = fs.readFileSync(absPath, 'utf8');
+                // Hash the content so we can detect real changes regardless of mtime.
+                const contentHash = createHash('sha256').update(content).digest('hex');
+                const existing = core.getDocumentWatermark?.(workspaceId, relativePath);
+                let updatedAt;
+                if (existing && existing.contentHash === contentHash) {
+                    // Content unchanged — use the stable stored timestamp.
+                    updatedAt = existing.updatedAt;
+                }
+                else {
+                    // New or changed content — seed from mtime, then persist.
+                    updatedAt = 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
+                });
+                workspaceCache.set(relativePath, {
+                    path: relativePath,
+                    mtimeMs: stat.mtimeMs,
+                    ctimeMs: stat.ctimeMs,
+                    size: stat.size,
+                    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 writeWorkspaceSyncDocument = (basePath, doc, workspaceId = 'default') => {
+        const normalizedPath = normalizeWorkspaceSyncDocumentPath(doc.path);
+        if (!normalizedPath)
+            return;
+        const root = path.resolve(path.join(basePath, '.taskforce'));
+        const targetPath = path.resolve(root, normalizedPath);
+        if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`))
+            return;
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        const content = String(doc.content || '');
+        fs.writeFileSync(targetPath, content, 'utf8');
+        const updatedAt = String(doc.updatedAt || '').trim();
+        const watermarkMs = Date.parse(updatedAt);
+        if (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());
+        }
+        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 deleteWorkspaceSyncDocument = (basePath, docPath, workspaceId = 'default') => {
+        const normalizedPath = normalizeWorkspaceSyncDocumentPath(docPath);
+        if (!normalizedPath)
+            return;
+        const root = path.resolve(path.join(basePath, '.taskforce'));
+        const targetPath = path.resolve(root, normalizedPath);
+        if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`))
+            return;
+        try {
+            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);
+        }
+        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) => {
+        const incomingMs = Date.parse(String(incomingWatermark || '').trim());
+        const existingMs = Date.parse(String(existingWatermark || '').trim());
+        const incomingHasWatermark = Number.isFinite(incomingMs);
+        const existingHasWatermark = Number.isFinite(existingMs);
+        if (incomingHasWatermark && existingHasWatermark) {
+            if (incomingMs > existingMs)
+                return 1;
+            if (incomingMs < existingMs)
+                return -1;
+        }
+        else if (incomingHasWatermark && !existingHasWatermark) {
+            return 1;
+        }
+        else if (!incomingHasWatermark && existingHasWatermark) {
+            return -1;
+        }
+        return incomingTieBreak.localeCompare(existingTieBreak);
+    };
+    const dispatchWorkspaceSyncChanges = (workspaceId, incomingChanges) => {
+        const tasks = [];
+        const archived = [];
+        const deleteTaskIds = new Set();
+        const emittedEventIds = new Set();
+        const unsubscribeRealtime = typeof core.onRealtimeMutation === 'function'
+            ? 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 incomingTaxonomiesUpdatedAt = '';
+        const incomingDocuments = [];
+        const incomingDocumentDeletes = new Set();
+        try {
+            for (const change of incomingChanges) {
+                const raw = change;
+                const op = String(raw.op || '').trim().toLowerCase();
+                if (op === 'taxonomy-upsert') {
+                    if (Array.isArray(raw.taxonomies)) {
+                        incomingTaxonomies = raw.taxonomies;
+                        incomingTaxonomiesUpdatedAt = String(raw.updatedAt || raw.watermark || '').trim();
+                    }
+                    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 : ''
+                        });
+                    }
+                    continue;
+                }
+                if (op === 'document-delete') {
+                    const normalizedPath = normalizeWorkspaceSyncDocumentPath(raw.path);
+                    if (normalizedPath)
+                        incomingDocumentDeletes.add(normalizedPath);
+                    continue;
+                }
+                if (op !== 'delete')
+                    continue;
+                const task = raw.task;
+                const deleteTaskId = String(raw.taskId || raw.id || task?.id || '').trim();
+                if (deleteTaskId)
+                    deleteTaskIds.add(deleteTaskId);
+            }
+            for (const change of incomingChanges) {
+                const raw = change;
+                const op = String(raw.op || '').trim().toLowerCase();
+                if (op === 'delete' || op === 'document-upsert' || op === 'document-delete')
+                    continue;
+                const task = raw.task && typeof raw.task === 'object' ? raw.task : null;
+                if (!task)
+                    continue;
+                const taskId = String(task.id || '').trim();
+                if (taskId && deleteTaskIds.has(taskId))
+                    continue;
+                const markedArchived = raw.archived === true || task?.isArchived === true;
+                if (markedArchived)
+                    archived.push(task);
+                else
+                    tasks.push(task);
+            }
+            for (const taskId of deleteTaskIds) {
+                try {
+                    if (typeof core.deleteTaskForSync === 'function') {
+                        core.deleteTaskForSync(taskId, workspaceId, { persistBackup: false });
+                    }
+                    else {
+                        core.deleteTask(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 (Array.isArray(incomingTaxonomies)) {
+                if (!incomingTaxonomiesUpdatedAt) {
+                    core.updateTaxonomies(incomingTaxonomies);
+                    const fallbackHash = createHash('sha256').update(JSON.stringify(incomingTaxonomies)).digest('hex');
+                    workspaceTaxonomySyncMeta.set(workspaceId, {
+                        updatedAt: new Date().toISOString(),
+                        hash: fallbackHash
+                    });
+                }
+                else {
+                    const incomingTaxonomyHash = createHash('sha256').update(JSON.stringify(incomingTaxonomies)).digest('hex');
+                    const currentMeta = workspaceTaxonomySyncMeta.get(workspaceId) || { updatedAt: '', hash: '' };
+                    const compare = resolveConflictOrdering(incomingTaxonomiesUpdatedAt, currentMeta.updatedAt, incomingTaxonomyHash, currentMeta.hash);
+                    if (compare >= 0) {
+                        core.updateTaxonomies(incomingTaxonomies);
+                        workspaceTaxonomySyncMeta.set(workspaceId, {
+                            updatedAt: incomingTaxonomiesUpdatedAt,
+                            hash: incomingTaxonomyHash
+                        });
+                    }
+                }
+            }
+            if (incomingDocuments.length > 0) {
+                for (const doc of incomingDocuments) {
+                    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);
+                    if (compare < 0)
+                        continue;
+                    if (compare === 0 && existingHash === incomingHash)
+                        continue;
+                    writeWorkspaceSyncDocument(core.getPaths().basePath, doc, workspaceId);
+                }
+            }
+            if (incomingDocumentDeletes.size > 0) {
+                for (const docPath of incomingDocumentDeletes) {
+                    deleteWorkspaceSyncDocument(core.getPaths().basePath, docPath, workspaceId);
+                }
+            }
+            const result = core.applyWorkspaceSyncSnapshot({ tasks, archived }, workspaceId);
+            return { result, deleteCount: deleteTaskIds.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);
+        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);
+        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 incomingTaxonomies = Array.isArray(body?.taxonomies) ? body.taxonomies : null;
+        const incomingDocuments = Array.isArray(body?.documents) ? body.documents : [];
+        try {
+            if (incomingTaxonomies) {
+                core.updateTaxonomies(incomingTaxonomies);
+            }
+            for (const doc of incomingDocuments) {
+                const docEntry = {
+                    path: String(doc?.path || '').trim(),
+                    updatedAt: String(doc?.updatedAt || '').trim(),
+                    content: typeof doc?.content === 'string' ? doc.content : ''
+                };
+                if (docEntry.path) {
+                    writeWorkspaceSyncDocument(core.getPaths().basePath, docEntry, cloudWorkspaceId);
+                }
+            }
+            const result = core.applyWorkspaceSyncSnapshot({
+                tasks,
+                archived
+            }, cloudWorkspaceId);
+            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,
+                documentCount: incomingDocuments.length
+            });
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            auditAuthAction(req, 'sync-workspace-bootstrap-failed', {
+                workspaceId: cloudWorkspaceId,
+                code: error?.code || null,
+                statusCode
+            });
+            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
+            }));
+        }
+    });
+    // GET /api/taskforce/sync/workspace/documents - Snapshot markdown documents for workspace sync payload/signature
+    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 basePath = core.getPaths().basePath;
+        const documents = listWorkspaceSyncDocumentsSnapshot(basePath, 'default');
+        const fingerprint = JSON.stringify(documents.map((doc) => `${doc.path}:${doc.updatedAt}:${doc.content.length}`));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            documents,
+            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 = typeof core.listTasksForSync === 'function'
+            ? core.listTasksForSync(targetWorkspaceId, syncCursor, dbFetchLimit)
+            : [
+                ...(core.listTasks(targetWorkspaceId)?.tasks || []).map((task) => ({ task, archived: false })),
+                ...(core.listArchive(targetWorkspaceId)?.archived || []).map((task) => ({ task, archived: true }))
+            ];
+        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 = typeof core.listWorkspaceSyncDeletesSince === 'function'
+            ? core.listWorkspaceSyncDeletesSince(targetWorkspaceId, syncCursor, dbFetchLimit)
+            : (typeof core.listWorkspaceSyncDeletes === 'function'
+                ? core.listWorkspaceSyncDeletes(targetWorkspaceId)
+                : []);
+        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 = (typeof core.getTaxonomiesSyncSnapshot === 'function'
+            ? core.getTaxonomiesSyncSnapshot()
+            : null);
+        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
+                }]
+            : [];
+        const documentEntries = 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 || '')
+        }))
+            .filter((entry) => Number.isFinite(Date.parse(entry.watermark)) && entry.path.length > 0);
+        const all = [...upsertEntries, ...deleteEntries, ...taxonomyEntries, ...documentEntries];
+        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);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            workspaceId: targetWorkspaceId,
+            changes: page.map((entry) => (entry.kind === 'delete'
+                ? {
+                    op: 'delete',
+                    taskId: entry.taskId,
+                    watermark: entry.watermark
+                }
+                : entry.kind === 'taxonomy'
+                    ? {
+                        op: 'taxonomy-upsert',
+                        taxonomies: entry.taxonomies,
+                        watermark: entry.watermark
+                    }
+                    : entry.kind === 'document'
+                        ? {
+                            op: 'document-upsert',
+                            path: entry.path,
+                            updatedAt: entry.watermark,
+                            content: entry.content,
+                            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);
+        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;
+            }
+            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 : [];
+        try {
+            const { result } = dispatchWorkspaceSyncChanges(workspaceId, incomingChanges);
+            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,
+                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,
+                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);
+        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;
+            }
+        }
+        const incomingChanges = Array.isArray(body?.changes) ? body.changes : [];
+        try {
+            const { result, deleteCount, emittedEventIds } = dispatchWorkspaceSyncChanges(targetWorkspaceId, incomingChanges);
+            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,
+                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,
+                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
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    });
+}