@taskforcehq/taskforce 0.3.170 → 0.3.301

package/dist/server/routes/sync.integration.test.js

@@ -0,0 +1,2003 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { Readable } from 'stream';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { TaskforceCore } from '../../core/Taskforce';
+import { createRoutes, matchRoute } from '../routes';
+import { createSessionTokenCookie } from '../auth';
+import { WorkspaceAssetStore } from '../../storage/workspaceAssetStore';
+function createMockReq(method, url, body, headers) {
+    const req = new Readable();
+    req._read = () => { };
+    req.push(body ? JSON.stringify(body) : null);
+    req.push(null);
+    req.method = method;
+    req.url = url;
+    req.headers = headers || {};
+    return req;
+}
+function createMockRes() {
+    return {
+        writeHead: vi.fn(),
+        end: vi.fn()
+    };
+}
+describe('Server Routes Workspace Sync Integration', () => {
+    const tempDirs = [];
+    const originalHome = process.env.HOME;
+    const workspaceId = 'workspace-local-active';
+    const authConfig = {
+        runtimeMode: 'cloud',
+        enabled: true,
+        requiredForApi: true,
+        excludedPaths: ['/api/taskforce/health', '/api/taskforce/version', '/api/taskforce/auth'],
+        defaultRole: 'member',
+        defaultWorkspaceId: '',
+        sessionCookieName: 'taskforce_session',
+        sessionSecret: 'integration-test-secret',
+        sessionTtlSeconds: 60 * 60,
+        sessionCookieSameSite: 'None',
+        sessionCookieSecure: true
+    };
+    const createAuthCookie = (overrideWorkspaceId) => createSessionTokenCookie('session-sync-integration', authConfig, {
+        role: 'owner',
+        workspaceId: overrideWorkspaceId || workspaceId,
+        userId: 'integration-user'
+    });
+    const readJsonBody = (res) => JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+    const createIsolatedProjectRoot = (prefix) => {
+        const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+        tempDirs.push(projectRoot);
+        process.env.HOME = projectRoot;
+        return projectRoot;
+    };
+    const buildSoftwareTaxonomyState = () => ({
+        categories: [
+            { value: 'default', label: 'General', icon: 'Inbox' },
+            { value: 'product', label: 'Product', icon: 'Layers', color: 'blue-500' }
+        ],
+        types: [
+            { value: 'feature', label: 'Feature', icon: 'Star', color: 'teal-500', status: 'active' },
+            { value: 'bug', label: 'Bug', icon: 'Bug', color: 'red-500', status: 'active' },
+            { value: 'chore', label: 'Chore', icon: 'Zap', color: 'amber-500', status: 'active' },
+            { value: 'refactor', label: 'Refactor', icon: 'Code', color: 'blue-500', status: 'active' },
+            { value: 'documentation', label: 'Docs', icon: 'Book', color: 'sky-500', status: 'active' }
+        ],
+        priorities: [
+            { value: 1, label: 'Low', color: 'amber-200', icon: 'ArrowDown' },
+            { value: 2, label: 'Medium', color: 'yellow-500', icon: 'Minus' },
+            { value: 3, label: 'High', color: 'orange-500', icon: 'ArrowUp' },
+            { value: 4, label: 'Critical', color: 'red-500', icon: 'AlertTriangle' }
+        ],
+        taxonomies: []
+    });
+    const seedAuthenticatedWorkspace = (core, options) => {
+        const userId = String(options?.userId || 'integration-user');
+        const targetWorkspaceId = String(options?.workspaceId || workspaceId);
+        const now = new Date().toISOString();
+        core.upsertPlanCatalog({ planId: 'starter', displayName: 'Starter' });
+        core.db.prepare(`
+            INSERT OR IGNORE INTO billing_price_mappings (
+                tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run('default', 'starter-v1', 'month', 'free:starter-v1:month', 'free', 1, 0, null, now, now);
+        core.upsertPlanCatalog({ planId: 'starter', displayName: 'Starter', status: 'active' });
+        core.db.prepare('INSERT OR IGNORE INTO users (id, tenant_id, email, created_at, updated_at) VALUES (?, ?, ?, ?, ?)').run(userId, 'default', `${userId}@test.com`, now, now);
+        core.updateAccountEntitlement({
+            accountId: userId,
+            planVersionId: 'starter-v1',
+            actorUserId: 'system',
+            actorRole: 'system_admin'
+        });
+        core.createWorkspaceForUser({
+            userId,
+            name: options?.name || 'Local Active Workspace',
+            role: 'owner',
+            preferredWorkspaceId: targetWorkspaceId
+        });
+    };
+    afterEach(() => {
+        process.env.HOME = originalHome;
+        while (tempDirs.length > 0) {
+            const dir = tempDirs.pop();
+            if (!dir)
+                continue;
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    it('persists cloud-pulled tasks into local sqlite via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-cloud-1',
+                        title: 'Task from cloud',
+                        status: 'in-progress',
+                        canceledReason: null
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        // Reload from disk to assert persistence, not just in-memory state.
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const persisted = reloadedCore.listTasks(workspaceId);
+        const task = persisted.tasks.find((item) => item.id === 'task-cloud-1');
+        const defaultWorkspaceTasks = reloadedCore.listTasks('default').tasks;
+        expect(task).toBeTruthy();
+        expect(task?.title).toBe('Task from cloud');
+        expect(task?.status).toBe('in-progress');
+        expect(defaultWorkspaceTasks.find((item) => item.id === 'task-cloud-1')).toBeUndefined();
+    });
+    it('persists synced comments via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-comments-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-cloud-comments-1',
+                        title: 'Task with synced comments',
+                        status: 'in-progress',
+                        updatedAt: '2026-03-16T12:00:00.000Z',
+                        comments: [
+                            {
+                                id: 'comment-cloud-1',
+                                author: 'user',
+                                text: 'Cloud comment',
+                                timestamp: '2026-03-16T12:00:00.000Z'
+                            }
+                        ]
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const persisted = reloadedCore.getTask('task-cloud-comments-1', workspaceId);
+        expect(persisted?.comments).toEqual([
+            expect.objectContaining({
+                id: 'comment-cloud-1',
+                author: 'user',
+                text: 'Cloud comment',
+                timestamp: '2026-03-16T12:00:00.000Z'
+            })
+        ]);
+    });
+    it('persists unattached annotated attachment sessions via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-annotated-unattached-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const assetStore = new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId());
+        assetStore.upsertAsset({
+            assetId: 'asset-image-sync-1',
+            workspaceId,
+            kind: 'image',
+            originalFilename: 'synced-image.png',
+            mimeType: 'image/png',
+            storageProvider: 'local',
+            storageKey: 'workspaces/workspace-local-active/assets/images/asset-image-sync-1-synced-image.png',
+            contentSha256: 'seed-hash-sync-image',
+            sizeBytes: 42,
+            createdAt: '2026-03-30T20:00:00.000Z',
+            updatedAt: '2026-03-30T20:00:00.000Z'
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'annotated-attachment-session-upsert',
+                    session: {
+                        id: 'session-unattached-apply-1',
+                        workspaceId,
+                        taskId: '',
+                        baseImageAssetId: 'asset-image-sync-1',
+                        title: 'Synced loose notes',
+                        globalInstruction: 'Review this image',
+                        annotations: [
+                            { id: 'annotation-1', kind: 'pin', order: 0, instruction: 'Look here', x: 0.2, y: 0.3 }
+                        ],
+                        createdByActorId: null,
+                        updatedByActorId: null,
+                        createdAt: '2026-03-30T20:00:00.000Z',
+                        updatedAt: '2026-03-30T20:05:00.000Z',
+                        deletedAt: null
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        expect(reloadedCore.listAnnotatedAttachmentSessions({
+            workspaceId,
+            taskId: '',
+            imageAssetId: 'asset-image-sync-1'
+        })).toEqual([
+            expect.objectContaining({
+                id: 'session-unattached-apply-1',
+                taskId: '',
+                baseImageAssetId: 'asset-image-sync-1',
+                title: 'Synced loose notes'
+            })
+        ]);
+    });
+    it('returns 500 when annotated attachment sync persistence fails during apply-local', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-annotated-failure-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        vi.spyOn(core, 'upsertAnnotatedAttachmentSessionForSync').mockImplementation(() => {
+            throw new Error('annotated sync failure');
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'annotated-attachment-session-upsert',
+                    session: {
+                        id: 'session-fail-1',
+                        workspaceId,
+                        taskId: '',
+                        baseImageAssetId: 'asset-image-sync-1',
+                        title: 'Broken notes',
+                        globalInstruction: null,
+                        annotations: [],
+                        createdByActorId: null,
+                        updatedByActorId: null,
+                        createdAt: '2026-03-30T20:00:00.000Z',
+                        updatedAt: '2026-03-30T20:05:00.000Z',
+                        deletedAt: null
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(500, expect.any(Object));
+        expect(readJsonBody(res)).toEqual(expect.objectContaining({
+            error: expect.stringContaining('Failed to persist annotated attachment session session-fail-1 during sync apply')
+        }));
+    });
+    it('persists synced ai profiles via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-ai-profiles-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'ai-profile-upsert',
+                    profile: {
+                        id: 'ai-profile-codex',
+                        workspaceId,
+                        profileToken: 'tfp_codex_sync',
+                        name: 'Codex',
+                        username: 'codex',
+                        icon: 'Bot',
+                        color: '#0ea5e9',
+                        surfaceType: 'coding_tool',
+                        createdAt: '2026-03-22T10:00:00.000Z',
+                        updatedAt: '2026-03-22T10:05:00.000Z',
+                        lastActiveAt: '2026-03-22T10:05:00.000Z'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        expect(reloadedCore.listAiProfiles(workspaceId)).toEqual([
+            expect.objectContaining({
+                id: 'ai-profile-codex',
+                name: 'Codex',
+                username: 'codex',
+                surfaceType: 'coding_tool'
+            })
+        ]);
+    });
+    it('rejects synced ai profiles with an invalid surfaceType via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-ai-profiles-invalid-surface-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'ai-profile-upsert',
+                    profile: {
+                        id: 'ai-profile-invalid',
+                        workspaceId,
+                        profileToken: 'tfp_invalid_surface',
+                        name: 'OpenClaw Agent',
+                        username: 'openclaw-agent',
+                        icon: 'Bot',
+                        color: '#64748b',
+                        surfaceType: 'desktop_app',
+                        createdAt: '2026-03-22T10:00:00.000Z',
+                        updatedAt: '2026-03-22T10:05:00.000Z',
+                        lastActiveAt: '2026-03-22T10:05:00.000Z'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+        expect(readJsonBody(res)).toEqual(expect.objectContaining({
+            code: 'AI_PROFILE_SURFACE_TYPE_INVALID',
+            error: expect.stringContaining('surfaceType')
+        }));
+    });
+    it('applies tasks whose assignee resolves after ai profile sync', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-ai-assignee-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'ai-profile-upsert',
+                    profile: {
+                        id: 'ai-profile-codex',
+                        workspaceId,
+                        profileToken: 'tfp_codex_sync',
+                        name: 'Codex',
+                        username: 'codex',
+                        icon: 'Bot',
+                        color: '#0ea5e9',
+                        surfaceType: 'coding_tool',
+                        createdAt: '2026-03-22T10:00:00.000Z',
+                        updatedAt: '2026-03-22T10:05:00.000Z',
+                        lastActiveAt: '2026-03-22T10:05:00.000Z'
+                    }
+                },
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-ai-assignee-1',
+                        title: 'Task assigned to synced AI',
+                        status: 'task',
+                        assignee: 'ai-profile-codex'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const task = reloadedCore.getTask('task-ai-assignee-1', workspaceId);
+        expect(task?.assignee).toBe('ai-profile-codex');
+        expect(task?.assigneeActor).toEqual(expect.objectContaining({
+            id: 'ai-profile-codex',
+            kind: 'ai',
+            label: 'Codex'
+        }));
+    });
+    it('applies tasks whose assignee resolves to a workspace member', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-human-assignee-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(core, { workspaceId, userId: 'member-1', name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-human-assignee-1',
+                        title: 'Task assigned to workspace member',
+                        status: 'task',
+                        assignee: 'member-1'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const task = reloadedCore.getTask('task-human-assignee-1', workspaceId);
+        expect(task?.assignee).toBe('member-1');
+        expect(task?.assigneeActor).toEqual(expect.objectContaining({
+            id: 'member-1',
+            kind: 'human'
+        }));
+    });
+    it('preserves unresolved human assignees during apply-local sync', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-unresolved-human-assignee-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-unresolved-human-assignee-1',
+                        title: 'Task assigned to remote human',
+                        status: 'task',
+                        assignee: 'user-019c91d9-c143-771d-b0bf-36e318cfb353'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const task = reloadedCore.getTask('task-unresolved-human-assignee-1', workspaceId);
+        expect(task?.assignee).toBe('user-019c91d9-c143-771d-b0bf-36e318cfb353');
+        expect(task?.assigneeActor).toEqual(expect.objectContaining({
+            id: 'user-019c91d9-c143-771d-b0bf-36e318cfb353',
+            kind: 'human',
+            meta: expect.objectContaining({ unresolved: true })
+        }));
+    });
+    it('still rejects unresolved ai assignees during apply-local sync', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-unresolved-ai-assignee-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-unresolved-ai-assignee-1',
+                        title: 'Task assigned to missing AI profile',
+                        status: 'task',
+                        assignee: 'ai-profile-missing'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+        expect(res.end).toHaveBeenCalledWith(expect.stringContaining('references unresolved assignee ai-profile-missing'));
+    });
+    it('persists archived cloud-pulled tasks into local sqlite archive via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-archived-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: true,
+                    task: {
+                        id: 'task-cloud-archived-1',
+                        title: 'Archived from cloud',
+                        status: 'done',
+                        isArchived: true
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const persistedArchive = reloadedCore.listArchive(workspaceId);
+        const archivedTask = persistedArchive.archived.find((item) => item.id === 'task-cloud-archived-1');
+        const defaultWorkspaceArchive = reloadedCore.listArchive('default').archived;
+        expect(archivedTask).toBeTruthy();
+        expect(archivedTask?.title).toBe('Archived from cloud');
+        expect(archivedTask?.isArchived).toBe(true);
+        expect(defaultWorkspaceArchive.find((item) => item.id === 'task-cloud-archived-1')).toBeUndefined();
+    });
+    it('persists archived task workstream links into local sqlite archive via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-archived-workstream-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createInitiative({
+            id: 'initiative-archived-sync-1',
+            title: 'Archived synced initiative',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, workspaceId);
+        core.createWorkstream({
+            id: 'workstream-archived-sync-1',
+            initiativeId: 'initiative-archived-sync-1',
+            title: 'Archived synced workstream',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, workspaceId);
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: true,
+                    task: {
+                        id: 'task-cloud-archived-linked-1',
+                        title: 'Archived linked task',
+                        status: 'done',
+                        workstreamId: 'workstream-archived-sync-1',
+                        isArchived: true,
+                        updatedAt: '2026-03-16T00:27:08.000Z'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const persistedArchive = reloadedCore.listArchive(workspaceId);
+        const archivedTask = persistedArchive.archived.find((item) => item.id === 'task-cloud-archived-linked-1');
+        expect(archivedTask).toBeTruthy();
+        expect(archivedTask?.isArchived).toBe(true);
+        expect(archivedTask?.workstreamId).toBe('workstream-archived-sync-1');
+    });
+    it('applies multiple terminal sync updates in one batch', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-terminal-status-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createTask({
+            id: 'task-terminal-1',
+            title: 'Terminal task 1',
+            status: 'task',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        core.createTask({
+            id: 'task-terminal-2',
+            title: 'Terminal task 2',
+            status: 'task',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-terminal-1',
+                        title: 'Terminal task 1',
+                        status: 'done',
+                        updatedAt: '2026-03-16T00:27:08.000Z'
+                    }
+                },
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-terminal-2',
+                        title: 'Terminal task 2',
+                        status: 'done',
+                        updatedAt: '2026-03-16T00:27:08.000Z'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const first = reloadedCore.getTask('task-terminal-1', workspaceId);
+        const second = reloadedCore.getTask('task-terminal-2', workspaceId);
+        expect(first?.status).toBe('done');
+        expect(second?.status).toBe('done');
+    });
+    it('preserves task workstream links when applying a synced snapshot', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-workstream-link-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createInitiative({
+            id: 'initiative-sync-1',
+            title: 'Synced initiative',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, workspaceId);
+        core.createWorkstream({
+            id: 'workstream-sync-1',
+            initiativeId: 'initiative-sync-1',
+            title: 'Synced workstream',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, workspaceId);
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-workstream-linked-1',
+                        title: 'Linked task',
+                        status: 'task',
+                        workstreamId: 'workstream-sync-1',
+                        updatedAt: '2026-03-16T00:27:08.000Z'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const task = reloadedCore.getTask('task-workstream-linked-1', workspaceId);
+        expect(task?.workstreamId).toBe('workstream-sync-1');
+    });
+    it('persists checklist items when applying a synced snapshot locally', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-checklist-apply-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-checklist-sync-1',
+                        title: 'Checklist sync task',
+                        status: 'task',
+                        updatedAt: '2026-03-16T00:27:08.000Z',
+                        checklistItems: [
+                            {
+                                id: 'checklist-sync-1',
+                                title: 'First synced item',
+                                isCompleted: false,
+                                order: 0,
+                                createdAt: '2026-03-16T00:00:00.000Z',
+                                updatedAt: '2026-03-16T00:27:08.000Z',
+                            },
+                            {
+                                id: 'checklist-sync-2',
+                                title: 'Second synced item',
+                                isCompleted: true,
+                                order: 1,
+                                createdAt: '2026-03-16T00:00:00.000Z',
+                                updatedAt: '2026-03-16T00:27:08.000Z',
+                            }
+                        ]
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const task = reloadedCore.getTask('task-checklist-sync-1', workspaceId);
+        expect(task?.checklistItems?.map((item) => item.title)).toEqual([
+            'First synced item',
+            'Second synced item',
+        ]);
+        expect(task?.checklistItems?.map((item) => item.isCompleted)).toEqual([false, true]);
+    });
+    it('serves synced workstream links back through the live cloud tasks route after push', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-cloud-workstream-route-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(core);
+        core.createInitiative({
+            id: 'initiative-cloud-1',
+            title: 'Cloud initiative',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, workspaceId);
+        core.createWorkstream({
+            id: 'workstream-cloud-1',
+            initiativeId: 'initiative-cloud-1',
+            title: 'Cloud workstream',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, workspaceId);
+        const routes = createRoutes(core, { authConfig });
+        const cookie = createAuthCookie(workspaceId);
+        const pushMatch = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+        expect(pushMatch).toBeTruthy();
+        const pushReq = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+            workspaceId,
+            idempotencyKey: 'push-cloud-workstream-link-1',
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-cloud-workstream-1',
+                        title: 'Cloud linked task',
+                        status: 'task',
+                        workstreamId: 'workstream-cloud-1',
+                        updatedAt: '2026-03-16T00:27:08.000Z'
+                    }
+                }
+            ]
+        }, { cookie });
+        const pushRes = createMockRes();
+        await pushMatch?.handler(pushReq, pushRes, {});
+        expect(pushRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const tasksMatch = matchRoute('GET', '/api/taskforce/tasks', routes);
+        expect(tasksMatch).toBeTruthy();
+        const tasksReq = createMockReq('GET', `/api/taskforce/tasks?workspaceId=${workspaceId}`, undefined, { cookie });
+        const tasksRes = createMockRes();
+        await tasksMatch?.handler(tasksReq, tasksRes, {});
+        expect(tasksRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const payload = readJsonBody(tasksRes);
+        const task = Array.isArray(payload?.tasks)
+            ? payload.tasks.find((entry) => entry?.id === 'task-cloud-workstream-1')
+            : null;
+        expect(task).toBeTruthy();
+        expect(task?.workstreamId).toBe('workstream-cloud-1');
+    });
+    it('prefers incoming workstream links when timestamps tie but task relationships differ', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-workstream-tie-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createInitiative({
+            id: 'initiative-sync-2',
+            title: 'Tie-break initiative',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, workspaceId);
+        core.createWorkstream({
+            id: 'workstream-sync-2',
+            initiativeId: 'initiative-sync-2',
+            title: 'Tie-break workstream',
+            createdAt: '2026-03-15T00:00:00.000Z',
+            updatedAt: '2026-03-15T00:00:00.000Z'
+        }, workspaceId);
+        core.createTask({
+            id: 'task-workstream-linked-2',
+            title: 'Linked task',
+            status: 'task',
+            updatedAt: '2026-03-16T00:27:08.000Z',
+            createdAt: '2026-03-16T00:00:00.000Z'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true,
+            syncUpdatedAt: '2026-03-16T00:27:08.000Z',
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-workstream-linked-2',
+                        title: 'Linked task',
+                        status: 'task',
+                        workstreamId: 'workstream-sync-2',
+                        updatedAt: '2026-03-16T00:27:08.000Z',
+                        createdAt: '2026-03-16T00:00:00.000Z'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const task = reloadedCore.getTask('task-workstream-linked-2', workspaceId);
+        expect(task?.workstreamId).toBe('workstream-sync-2');
+    });
+    it('prefers incoming checklist changes when timestamps tie but checklist content differs', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-checklist-tie-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createTask({
+            id: 'task-checklist-sync-2',
+            title: 'Checklist tie-break task',
+            status: 'task',
+            updatedAt: '2026-03-16T00:27:08.000Z',
+            createdAt: '2026-03-16T00:00:00.000Z',
+            checklistItems: [
+                {
+                    id: 'checklist-existing-1',
+                    taskId: 'task-checklist-sync-2',
+                    title: 'Old local item',
+                    isCompleted: false,
+                    order: 0,
+                    createdAt: '2026-03-16T00:00:00.000Z',
+                    updatedAt: '2026-03-16T00:27:08.000Z',
+                }
+            ]
+        }, { workspaceId, allowClientProvidedId: true });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-checklist-sync-2',
+                        title: 'Checklist tie-break task',
+                        status: 'task',
+                        updatedAt: '2026-03-16T00:27:08.000Z',
+                        checklistItems: [
+                            {
+                                id: 'checklist-incoming-1',
+                                title: 'Incoming synced item',
+                                isCompleted: true,
+                                order: 0,
+                                createdAt: '2026-03-16T00:00:00.000Z',
+                                updatedAt: '2026-03-16T00:27:08.000Z',
+                            }
+                        ]
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const task = reloadedCore.getTask('task-checklist-sync-2', workspaceId);
+        expect(task?.checklistItems?.map((item) => item.title)).toEqual(['Incoming synced item']);
+        expect(task?.checklistItems?.map((item) => item.isCompleted)).toEqual([true]);
+    });
+    it('does not let an older pulled snapshot revert a newer local in-progress update', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-newer-local-status-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createTask({
+            id: 'task-status-1',
+            title: 'Task status',
+            status: 'task',
+            createdAt: '2026-03-16T00:00:00.000Z'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const locallyUpdated = core.updateTask('task-status-1', {
+            status: 'in-progress'
+        }, workspaceId, { persistBackup: false });
+        expect(locallyUpdated?.status).toBe('in-progress');
+        expect(String(locallyUpdated?.updatedAt || '')).not.toBe('');
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-status-1',
+                        title: 'Task status',
+                        status: 'task',
+                        updatedAt: '2026-03-16T00:00:01.000Z'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const persisted = reloadedCore.getTask('task-status-1', workspaceId);
+        expect(persisted?.status).toBe('in-progress');
+        expect(Date.parse(String(persisted?.updatedAt || ''))).toBeGreaterThan(Date.parse('2026-03-16T00:00:01.000Z'));
+    });
+    it('applies cloud delete operations to local sqlite across reload via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-delete-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedCore.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        seedCore.updateTaxonomyState(buildSoftwareTaxonomyState(), workspaceId);
+        const seeded = seedCore.createTask({
+            title: 'Will be deleted by cloud sync',
+            category: 'Default',
+            type: 'feature',
+            priority: 2,
+            status: 'task'
+        }, { workspaceId });
+        expect(seeded.id).toBeTruthy();
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                { op: 'delete', taskId: seeded.id }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const persisted = reloadedCore.listTasks(workspaceId);
+        const deletedTask = persisted.tasks.find((item) => item.id === seeded.id);
+        expect(deletedTask).toBeUndefined();
+    });
+    it('keeps task deleted when apply-local receives same-task upsert and delete in one batch', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-delete-wins-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedCore.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        seedCore.updateTaxonomyState(buildSoftwareTaxonomyState(), workspaceId);
+        const seeded = seedCore.createTask({
+            title: 'Seed task for delete-wins',
+            category: 'Default',
+            type: 'feature',
+            priority: 2,
+            status: 'task'
+        }, { workspaceId });
+        expect(seeded.id).toBeTruthy();
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: seeded.id,
+                        title: 'Stale cloud upsert'
+                    }
+                },
+                { op: 'delete', taskId: seeded.id }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const persisted = reloadedCore.listTasks(workspaceId);
+        const shouldRemainDeleted = persisted.tasks.find((item) => item.id === seeded.id);
+        expect(shouldRemainDeleted).toBeUndefined();
+    });
+    it('applies document-delete operations by deleting file and clearing watermark index', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-doc-delete-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedCore.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const syncRoot = seedCore.getPaths().basePath;
+        const docsDir = path.join(syncRoot, 'docs');
+        fs.mkdirSync(docsDir, { recursive: true });
+        const relativeDocPath = 'docs/sync-delete.md';
+        const absoluteDocPath = path.join(syncRoot, relativeDocPath);
+        fs.writeFileSync(absoluteDocPath, '# sync delete\n', 'utf8');
+        seedCore.upsertDocumentWatermark(workspaceId, relativeDocPath, 'seed-hash', '2026-02-23T00:00:00.000Z');
+        expect(seedCore.getDocumentWatermark(workspaceId, relativeDocPath)).toBeTruthy();
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                { op: 'document-delete', path: relativeDocPath }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        expect(fs.existsSync(absoluteDocPath)).toBe(false);
+        expect(reloadedCore.getDocumentWatermark(workspaceId, relativeDocPath)).toBeNull();
+    });
+    it('persists canonical markdown asset metadata across reload via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-doc-asset-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createTask({
+            id: 'task-doc-asset-1',
+            title: 'Task with synced markdown asset',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const relativeDocPath = 'docs/phase1-sync.md';
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'document-upsert',
+                    path: relativeDocPath,
+                    updatedAt: '2026-03-17T12:00:00.000Z',
+                    content: '# canonical markdown\n',
+                    assetId: 'asset-doc-sync-1',
+                    documentId: 'doc-sync-1',
+                    version: 3,
+                    taskId: 'task-doc-asset-1',
+                    originalFilename: 'phase1-sync.md',
+                    linkRole: 'attachment'
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const absoluteDocPath = path.join(reloadedCore.getPaths().basePath, relativeDocPath);
+        const store = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        const asset = store.get('asset-doc-sync-1', workspaceId);
+        const links = store.listLinksForAsset('asset-doc-sync-1', workspaceId);
+        expect(fs.readFileSync(absoluteDocPath, 'utf8')).toBe('# canonical markdown\n');
+        expect(reloadedCore.getDocumentWatermark(workspaceId, relativeDocPath)).toEqual({
+            updatedAt: '2026-03-17T12:00:00.000Z',
+            contentHash: expect.any(String)
+        });
+        expect(asset).toEqual(expect.objectContaining({
+            assetId: 'asset-doc-sync-1',
+            workspaceId,
+            kind: 'document',
+            storageProvider: 'local',
+            storageKey: relativeDocPath,
+            documentId: 'doc-sync-1',
+            version: 3,
+            originalFilename: 'phase1-sync.md',
+            mimeType: 'text/markdown',
+            deletedAt: null
+        }));
+        expect(links).toEqual([
+            expect.objectContaining({
+                assetId: 'asset-doc-sync-1',
+                workspaceId,
+                taskId: 'task-doc-asset-1',
+                role: 'attachment',
+                deletedAt: null
+            })
+        ]);
+    });
+    it('retries document asset reference allocation during apply-local when persistence hits a collision', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-doc-asset-collision-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createTask({
+            id: 'task-doc-asset-collision-1',
+            title: 'Task with collided synced markdown asset',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const db = core.getDatabaseAdapter();
+        const seededStore = new WorkspaceAssetStore(db, core.getTenantId());
+        seededStore.upsertAsset({
+            assetId: 'asset-doc-existing-collision',
+            workspaceId,
+            kind: 'document',
+            originalFilename: 'existing.md',
+            mimeType: 'text/markdown',
+            storageProvider: 'local',
+            storageKey: 'docs/existing-collision.md',
+            contentSha256: 'sha-existing-collision',
+            sizeBytes: 10,
+            referenceNumber: 7,
+            createdAt: '2026-03-17T11:55:00.000Z',
+            updatedAt: '2026-03-17T11:55:00.000Z'
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const relativeDocPath = 'docs/phase1-sync-collision.md';
+        const originalPrepare = db.prepare.bind(db);
+        let forcedCollision = false;
+        vi.spyOn(db, 'prepare').mockImplementation((...args) => {
+            const [sql] = args;
+            const statement = originalPrepare(...args);
+            if (typeof sql !== 'string') {
+                return statement;
+            }
+            if (!sql.includes('INSERT INTO workspace_assets')) {
+                return statement;
+            }
+            return {
+                ...statement,
+                run: (...args) => {
+                    const storageKeyArg = args[8];
+                    const referenceNumberArg = args[12];
+                    if (!forcedCollision
+                        && storageKeyArg === relativeDocPath
+                        && referenceNumberArg === 8) {
+                        forcedCollision = true;
+                        throw new Error('UNIQUE constraint failed: workspace_assets.tenant_id, workspace_assets.workspace_id, workspace_assets.kind, workspace_assets.reference_number');
+                    }
+                    return statement.run(...args);
+                }
+            };
+        });
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'document-upsert',
+                    path: relativeDocPath,
+                    updatedAt: '2026-03-17T12:00:00.000Z',
+                    content: '# canonical markdown after collision\n',
+                    assetId: 'asset-doc-sync-collision-1',
+                    documentId: 'doc-sync-collision-1',
+                    referenceNumber: 8,
+                    version: 3,
+                    taskId: 'task-doc-asset-collision-1',
+                    originalFilename: 'phase1-sync-collision.md',
+                    linkRole: 'attachment'
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(forcedCollision).toBe(true);
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const absoluteDocPath = path.join(reloadedCore.getPaths().basePath, relativeDocPath);
+        const store = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        const asset = store.get('asset-doc-sync-collision-1', workspaceId);
+        const links = store.listLinksForAsset('asset-doc-sync-collision-1', workspaceId);
+        const syncEvents = reloadedCore.listSyncEvents(workspaceId, 20);
+        expect(fs.readFileSync(absoluteDocPath, 'utf8')).toBe('# canonical markdown after collision\n');
+        expect(asset).toEqual(expect.objectContaining({
+            assetId: 'asset-doc-sync-collision-1',
+            workspaceId,
+            kind: 'document',
+            storageKey: relativeDocPath,
+            documentId: 'doc-sync-collision-1',
+            version: 3,
+            referenceNumber: 9,
+            deletedAt: null
+        }));
+        expect(links).toEqual([
+            expect.objectContaining({
+                assetId: 'asset-doc-sync-collision-1',
+                workspaceId,
+                taskId: 'task-doc-asset-collision-1',
+                role: 'attachment',
+                deletedAt: null
+            })
+        ]);
+        expect(syncEvents.some((event) => event.errorMessage === 'Failed to persist document watermark after write.')).toBe(false);
+    });
+    it('persists canonical binary assets across reload via apply-local route', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-binary-asset-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.createTask({
+            id: 'task-binary-asset-1',
+            title: 'Task with synced binary asset',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const relativeAssetPath = 'workspaces/workspace-local-active/assets/images/asset-binary-sync-1-synced-image.png';
+        const assetBuffer = Buffer.from('binary-image-content');
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'asset-upsert',
+                    path: relativeAssetPath,
+                    updatedAt: '2026-03-17T12:05:00.000Z',
+                    contentBase64: assetBuffer.toString('base64'),
+                    assetId: 'asset-binary-sync-1',
+                    kind: 'image',
+                    mimeType: 'image/png',
+                    taskId: 'task-binary-asset-1',
+                    originalFilename: 'synced-image.png',
+                    linkRole: 'image'
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const absoluteAssetPath = path.join(reloadedCore.getPaths().basePath, relativeAssetPath);
+        const store = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        const asset = store.get('asset-binary-sync-1', workspaceId);
+        const links = store.listLinksForAsset('asset-binary-sync-1', workspaceId);
+        expect(fs.readFileSync(absoluteAssetPath)).toEqual(assetBuffer);
+        expect(asset).toEqual(expect.objectContaining({
+            assetId: 'asset-binary-sync-1',
+            workspaceId,
+            kind: 'image',
+            storageProvider: 'local',
+            storageKey: relativeAssetPath,
+            originalFilename: 'synced-image.png',
+            mimeType: 'image/png',
+            deletedAt: null
+        }));
+        expect(links).toEqual([
+            expect.objectContaining({
+                assetId: 'asset-binary-sync-1',
+                workspaceId,
+                taskId: 'task-binary-asset-1',
+                role: 'image',
+                deletedAt: null
+            })
+        ]);
+    });
+    it('round-trips cloud attachment links for canonical markdown and file assets into local apply', async () => {
+        const cloudProjectRoot = createIsolatedProjectRoot('taskforce-sync-cloud-link-roundtrip-cloud-');
+        const localProjectRoot = createIsolatedProjectRoot('taskforce-sync-cloud-link-roundtrip-local-');
+        const cloudCore = new TaskforceCore({ projectRoot: cloudProjectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(cloudCore);
+        cloudCore.createTask({
+            id: 'task-cloud-link-roundtrip-1',
+            title: 'Cloud attachment source',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const cloudBasePath = cloudCore.getPaths().basePath;
+        const cloudStore = new WorkspaceAssetStore(cloudCore.getDatabaseAdapter(), cloudCore.getTenantId());
+        const markdownPath = `workspaces/${workspaceId}/assets/documents/asset-cloud-link-roundtrip-plan.md`;
+        const filePath = `workspaces/${workspaceId}/assets/files/asset-cloud-link-roundtrip-notes.txt`;
+        fs.mkdirSync(path.dirname(path.join(cloudBasePath, markdownPath)), { recursive: true });
+        fs.mkdirSync(path.dirname(path.join(cloudBasePath, filePath)), { recursive: true });
+        fs.writeFileSync(path.join(cloudBasePath, markdownPath), '# synced from cloud\n', 'utf8');
+        fs.writeFileSync(path.join(cloudBasePath, filePath), 'cloud text attachment', 'utf8');
+        cloudStore.upsertAsset({
+            assetId: 'asset-cloud-link-roundtrip-doc-1',
+            workspaceId,
+            kind: 'document',
+            originalFilename: 'plan.md',
+            mimeType: 'text/markdown',
+            storageProvider: 'local',
+            storageKey: markdownPath,
+            contentSha256: 'doc-roundtrip-hash',
+            sizeBytes: '# synced from cloud\n'.length,
+            documentId: 'doc-cloud-link-roundtrip-1',
+            version: 1,
+            isLatest: true,
+            createdAt: '2026-03-18T09:00:00.000Z',
+            updatedAt: '2026-03-18T09:00:00.000Z'
+        });
+        cloudStore.upsertLink({
+            workspaceId,
+            assetId: 'asset-cloud-link-roundtrip-doc-1',
+            taskId: 'task-cloud-link-roundtrip-1',
+            role: 'attachment',
+            updatedAt: '2026-03-18T10:00:00.000Z'
+        });
+        cloudStore.upsertAsset({
+            assetId: 'asset-cloud-link-roundtrip-file-1',
+            workspaceId,
+            kind: 'file',
+            originalFilename: 'notes.txt',
+            mimeType: 'text/plain',
+            storageProvider: 'local',
+            storageKey: filePath,
+            contentSha256: 'file-roundtrip-hash',
+            sizeBytes: 'cloud text attachment'.length,
+            isLatest: true,
+            createdAt: '2026-03-18T09:00:00.000Z',
+            updatedAt: '2026-03-18T09:00:00.000Z'
+        });
+        cloudStore.upsertLink({
+            workspaceId,
+            assetId: 'asset-cloud-link-roundtrip-file-1',
+            taskId: 'task-cloud-link-roundtrip-1',
+            role: 'attachment',
+            updatedAt: '2026-03-18T10:00:01.000Z'
+        });
+        const cloudRoutes = createRoutes(cloudCore, { authConfig });
+        const pullMatch = matchRoute('GET', '/api/taskforce/sync/workspace/pull', cloudRoutes);
+        expect(pullMatch).toBeTruthy();
+        const cookie = createAuthCookie(workspaceId);
+        const pullReq = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-local-active&limit=50&cursor=eyJ1IjoiMjAyNi0wMy0xOFQwOTozMDowMC4wMDBaIiwiaWQiOiJzZWVkIn0', undefined, { cookie });
+        const pullRes = createMockRes();
+        await pullMatch?.handler(pullReq, pullRes, {});
+        expect(pullRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const pullBody = readJsonBody(pullRes);
+        const pulledChanges = Array.isArray(pullBody?.changes) ? pullBody.changes : [];
+        expect(pulledChanges).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                op: 'document-upsert',
+                path: markdownPath,
+                assetId: 'asset-cloud-link-roundtrip-doc-1',
+                taskId: 'task-cloud-link-roundtrip-1',
+                originalFilename: 'plan.md',
+                linkRole: 'attachment'
+            }),
+            expect.objectContaining({
+                op: 'asset-upsert',
+                path: filePath,
+                assetId: 'asset-cloud-link-roundtrip-file-1',
+                taskId: 'task-cloud-link-roundtrip-1',
+                originalFilename: 'notes.txt',
+                linkRole: 'attachment'
+            })
+        ]));
+        const localCore = new TaskforceCore({ projectRoot: localProjectRoot, storagePath: '.taskforce' });
+        localCore.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        localCore.createTask({
+            id: 'task-cloud-link-roundtrip-1',
+            title: 'Local attachment target',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const localRoutes = createRoutes(localCore, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const applyMatch = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', localRoutes);
+        expect(applyMatch).toBeTruthy();
+        const applyReq = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', { changes: pulledChanges }, { 'x-taskforce-workspace-id': workspaceId });
+        const applyRes = createMockRes();
+        await applyMatch?.handler(applyReq, applyRes, {});
+        expect(applyRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedLocalCore = new TaskforceCore({ projectRoot: localProjectRoot, storagePath: '.taskforce' });
+        const reloadedStore = new WorkspaceAssetStore(reloadedLocalCore.getDatabaseAdapter(), reloadedLocalCore.getTenantId());
+        expect(fs.readFileSync(path.join(reloadedLocalCore.getPaths().basePath, markdownPath), 'utf8')).toBe('# synced from cloud\n');
+        expect(fs.readFileSync(path.join(reloadedLocalCore.getPaths().basePath, filePath), 'utf8')).toBe('cloud text attachment');
+        expect(reloadedStore.listLinksForAsset('asset-cloud-link-roundtrip-doc-1', workspaceId)).toEqual([
+            expect.objectContaining({
+                taskId: 'task-cloud-link-roundtrip-1',
+                role: 'attachment',
+                deletedAt: null
+            })
+        ]);
+        expect(reloadedStore.listLinksForAsset('asset-cloud-link-roundtrip-file-1', workspaceId)).toEqual([
+            expect.objectContaining({
+                taskId: 'task-cloud-link-roundtrip-1',
+                role: 'attachment',
+                deletedAt: null
+            })
+        ]);
+    });
+    it('propagates document-delete through authenticated push and omits deleted doc from pull payload', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-push-pull-doc-delete-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(seedCore);
+        const syncRoot = seedCore.getPaths().basePath;
+        const docsDir = path.join(syncRoot, 'docs');
+        fs.mkdirSync(docsDir, { recursive: true });
+        const relativeDocPath = 'docs/sync-delete-push.md';
+        const absoluteDocPath = path.join(syncRoot, relativeDocPath);
+        fs.writeFileSync(absoluteDocPath, '# from local\n', 'utf8');
+        seedCore.upsertDocumentWatermark(workspaceId, relativeDocPath, 'seed-hash', '2026-02-23T00:00:00.000Z');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig });
+        const pushMatch = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+        const pullMatch = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+        expect(pushMatch).toBeTruthy();
+        expect(pullMatch).toBeTruthy();
+        const cookie = createAuthCookie(workspaceId);
+        const pushReq = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+            workspaceId,
+            idempotencyKey: 'doc-delete-integration-1',
+            changes: [
+                { op: 'document-delete', path: relativeDocPath }
+            ]
+        }, { cookie });
+        const pushRes = createMockRes();
+        await pushMatch?.handler(pushReq, pushRes, {});
+        expect(pushRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        expect(fs.existsSync(absoluteDocPath)).toBe(false);
+        expect(reloadedCore.getDocumentWatermark(workspaceId, relativeDocPath)).toBeNull();
+        const pullReq = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-local-active&limit=200', undefined, { cookie });
+        const pullRes = createMockRes();
+        await pullMatch?.handler(pullReq, pullRes, {});
+        expect(pullRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const pullBody = readJsonBody(pullRes);
+        const documentUpserts = (Array.isArray(pullBody?.changes) ? pullBody.changes : [])
+            .filter((change) => String(change?.op || '').toLowerCase() === 'document-upsert');
+        expect(documentUpserts.find((change) => change.path === relativeDocPath)).toBeUndefined();
+    });
+    it('round-trips task comments through authenticated push and pull payloads', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-push-pull-comments-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(seedCore);
+        const created = seedCore.createTask({
+            title: 'Comment sync task',
+            status: 'task'
+        }, { workspaceId });
+        seedCore.addComment(created.id, 'Synced activity comment', 'user', workspaceId);
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig });
+        const pushMatch = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+        const pullMatch = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+        expect(pushMatch).toBeTruthy();
+        expect(pullMatch).toBeTruthy();
+        const cookie = createAuthCookie(workspaceId);
+        const currentTask = core.getTask(created.id, workspaceId);
+        expect(currentTask?.comments).toHaveLength(1);
+        expect(currentTask?.comments?.[0]?.submittedAuthor).toBe('user');
+        const pushReq = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+            workspaceId,
+            idempotencyKey: 'comment-roundtrip-1',
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: currentTask
+                }
+            ]
+        }, { cookie });
+        const pushRes = createMockRes();
+        await pushMatch?.handler(pushReq, pushRes, {});
+        expect(pushRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const pullReq = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-local-active&limit=200', undefined, { cookie });
+        const pullRes = createMockRes();
+        await pullMatch?.handler(pullReq, pullRes, {});
+        expect(pullRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const pullBody = readJsonBody(pullRes);
+        const upsert = (Array.isArray(pullBody?.changes) ? pullBody.changes : [])
+            .find((change) => change?.op === 'upsert' && change?.task?.id === created.id);
+        expect(upsert?.task?.comments).toEqual([
+            expect.objectContaining({
+                id: expect.any(String),
+                author: 'user',
+                submittedAuthor: 'user',
+                text: 'Synced activity comment',
+                timestamp: expect.any(String)
+            })
+        ]);
+    });
+    it('keeps document deleted when push batch includes upsert and delete for same path', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-push-doc-delete-wins-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(seedCore);
+        const syncRoot = seedCore.getPaths().basePath;
+        const docsDir = path.join(syncRoot, 'docs');
+        fs.mkdirSync(docsDir, { recursive: true });
+        const relativeDocPath = 'docs/sync-delete-wins.md';
+        const absoluteDocPath = path.join(syncRoot, relativeDocPath);
+        fs.writeFileSync(absoluteDocPath, '# old\n', 'utf8');
+        seedCore.upsertDocumentWatermark(workspaceId, relativeDocPath, 'seed-hash', '2026-02-23T00:00:00.000Z');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig });
+        const pushMatch = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+        expect(pushMatch).toBeTruthy();
+        const cookie = createAuthCookie(workspaceId);
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+            workspaceId,
+            idempotencyKey: 'doc-delete-integration-2',
+            changes: [
+                {
+                    op: 'document-upsert',
+                    path: relativeDocPath,
+                    updatedAt: '2026-02-23T10:00:00.000Z',
+                    content: '# stale upsert'
+                },
+                {
+                    op: 'document-delete',
+                    path: relativeDocPath
+                }
+            ]
+        }, { cookie });
+        const res = createMockRes();
+        await pushMatch?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        expect(fs.existsSync(absoluteDocPath)).toBe(false);
+        expect(core.getDocumentWatermark(workspaceId, relativeDocPath)).toBeNull();
+    });
+    it('propagates binary asset deletes through authenticated push and persists canonical tombstones', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-push-pull-asset-delete-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(seedCore);
+        seedCore.createTask({
+            id: 'task-asset-delete-1',
+            title: 'Asset delete task',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        const relativeAssetPath = 'workspaces/workspace-local-active/assets/files/asset-delete-auth-1-delete-me.bin';
+        const absoluteAssetPath = path.join(seedCore.getPaths().basePath, relativeAssetPath);
+        fs.mkdirSync(path.dirname(absoluteAssetPath), { recursive: true });
+        fs.writeFileSync(absoluteAssetPath, Buffer.from('delete-me'));
+        const seededStore = new WorkspaceAssetStore(seedCore.getDatabaseAdapter(), seedCore.getTenantId());
+        seededStore.upsertAsset({
+            assetId: 'asset-delete-auth-1',
+            workspaceId,
+            kind: 'file',
+            originalFilename: 'delete-me.bin',
+            mimeType: 'application/octet-stream',
+            storageProvider: 'local',
+            storageKey: relativeAssetPath,
+            contentSha256: 'seed-hash',
+            sizeBytes: 9,
+            createdAt: '2026-03-17T11:00:00.000Z',
+            updatedAt: '2026-03-17T11:00:00.000Z'
+        });
+        seededStore.upsertLink({
+            workspaceId,
+            assetId: 'asset-delete-auth-1',
+            taskId: 'task-asset-delete-1',
+            role: 'attachment',
+            updatedAt: '2026-03-17T11:00:00.000Z'
+        });
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig });
+        const pushMatch = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+        const pullMatch = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+        expect(pushMatch).toBeTruthy();
+        expect(pullMatch).toBeTruthy();
+        const cookie = createAuthCookie(workspaceId);
+        const pushReq = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+            workspaceId,
+            idempotencyKey: 'asset-delete-integration-1',
+            changes: [
+                {
+                    op: 'asset-delete',
+                    path: relativeAssetPath,
+                    assetId: 'asset-delete-auth-1'
+                }
+            ]
+        }, { cookie });
+        const pushRes = createMockRes();
+        await pushMatch?.handler(pushReq, pushRes, {});
+        expect(pushRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const reloadedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const reloadedStore = new WorkspaceAssetStore(reloadedCore.getDatabaseAdapter(), reloadedCore.getTenantId());
+        const deletedAsset = reloadedStore.get('asset-delete-auth-1', workspaceId);
+        const deletedLinks = reloadedStore.listLinksForAsset('asset-delete-auth-1', workspaceId, { includeDeleted: true });
+        expect(fs.existsSync(absoluteAssetPath)).toBe(false);
+        expect(deletedAsset?.deletedAt).toEqual(expect.any(String));
+        expect(deletedLinks).toEqual([
+            expect.objectContaining({
+                assetId: 'asset-delete-auth-1',
+                workspaceId,
+                taskId: 'task-asset-delete-1',
+                role: 'attachment',
+                deletedAt: expect.any(String)
+            })
+        ]);
+        const pullReq = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-local-active&limit=200', undefined, { cookie });
+        const pullRes = createMockRes();
+        await pullMatch?.handler(pullReq, pullRes, {});
+        expect(pullRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const pullBody = readJsonBody(pullRes);
+        const assetUpserts = (Array.isArray(pullBody?.changes) ? pullBody.changes : [])
+            .filter((change) => String(change?.op || '').toLowerCase() === 'asset-upsert');
+        const assetDeletes = (Array.isArray(pullBody?.changes) ? pullBody.changes : [])
+            .filter((change) => String(change?.op || '').toLowerCase() === 'asset-delete');
+        expect(assetUpserts.find((change) => change.path === relativeAssetPath)).toBeUndefined();
+        expect(assetDeletes).toContainEqual(expect.objectContaining({
+            op: 'asset-delete',
+            path: relativeAssetPath,
+            assetId: 'asset-delete-auth-1'
+        }));
+    });
+    it('includes unattached annotated attachment sessions in the authenticated sync snapshot', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-annotated-snapshot-');
+        const seedCore = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(seedCore);
+        const seededStore = new WorkspaceAssetStore(seedCore.getDatabaseAdapter(), seedCore.getTenantId());
+        seededStore.upsertAsset({
+            assetId: 'asset-image-unattached-1',
+            workspaceId,
+            kind: 'image',
+            originalFilename: 'unattached.png',
+            mimeType: 'image/png',
+            storageProvider: 'local',
+            storageKey: 'workspaces/workspace-local-active/assets/images/asset-image-unattached-1-unattached.png',
+            contentSha256: 'seed-hash-unattached',
+            sizeBytes: 42,
+            createdAt: '2026-03-30T20:00:00.000Z',
+            updatedAt: '2026-03-30T20:00:00.000Z'
+        });
+        seedCore.createAnnotatedAttachmentSession({
+            workspaceId,
+            baseImageAssetId: 'asset-image-unattached-1',
+            title: 'Loose image notes',
+            annotations: [
+                { id: 'annotation-1', kind: 'pin', order: 0, instruction: 'Check this', x: 0.2, y: 0.3 },
+            ],
+        });
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        const routes = createRoutes(core, { authConfig });
+        const snapshotMatch = matchRoute('GET', '/api/taskforce/sync/workspace/annotated-attachments', routes);
+        expect(snapshotMatch).toBeTruthy();
+        const cookie = createAuthCookie(workspaceId);
+        const req = createMockReq('GET', '/api/taskforce/sync/workspace/annotated-attachments?workspaceId=workspace-local-active', undefined, { cookie });
+        const res = createMockRes();
+        await snapshotMatch?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        expect(readJsonBody(res).sessions).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                baseImageAssetId: 'asset-image-unattached-1',
+                taskId: '',
+                title: 'Loose image notes'
+            })
+        ]));
+    });
+    it('returns 401 on apply-local when auth is enabled but absent', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-auth-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        // Enable auth this time as we are testing it
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: true } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', { changes: [] }, { 'x-taskforce-workspace-id': workspaceId }
+        // No auth cookie or session
+        );
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(401, expect.any(Object));
+    });
+    it('round-trips sync event details through the sync events API', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-events-details-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const postMatch = matchRoute('POST', '/api/taskforce/sync/events', routes);
+        expect(postMatch).toBeTruthy();
+        const postReq = createMockReq('POST', '/api/taskforce/sync/events', {
+            workspaceId,
+            eventType: 'apply',
+            status: 'error',
+            errorMessage: 'Detected asset reference number mismatch during normal sync.',
+            details: {
+                path: 'workspaces/workspace-local-active/assets/images/hero.png',
+                existingReferenceNumber: 12,
+                incomingReferenceNumber: 18
+            }
+        });
+        const postRes = createMockRes();
+        await postMatch?.handler(postReq, postRes, {});
+        expect(postRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const getMatch = matchRoute('GET', '/api/taskforce/sync/events', routes);
+        expect(getMatch).toBeTruthy();
+        const getReq = createMockReq('GET', `/api/taskforce/sync/events?workspace_id=${workspaceId}&limit=5`);
+        const getRes = createMockRes();
+        await getMatch?.handler(getReq, getRes, {});
+        expect(getRes.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const payload = JSON.parse(String(getRes.end.mock.calls[0]?.[0] || '{}'));
+        expect(payload.events).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                eventType: 'apply',
+                status: 'error',
+                errorMessage: 'Detected asset reference number mismatch during normal sync.',
+                details: expect.objectContaining({
+                    path: 'workspaces/workspace-local-active/assets/images/hero.png',
+                    existingReferenceNumber: 12,
+                    incomingReferenceNumber: 18
+                })
+            })
+        ]));
+    });
+    it('returns 400 on apply-local when workspaceId is null/empty/default', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-wsmissing-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        // Use false for auth to isolate workspaceId testing
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', { changes: [] }
+        // Omit custom headers, and the body does not have workspaceId
+        );
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+    });
+    it('keeps repeated document scans correct and invalidates cache when file content changes', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-doc-cache-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const syncRoot = core.getPaths().basePath;
+        const docsDir = path.join(syncRoot, 'docs');
+        fs.mkdirSync(docsDir, { recursive: true });
+        const relativeDocPath = 'docs/cache-target.md';
+        const absoluteDocPath = path.join(syncRoot, relativeDocPath);
+        fs.writeFileSync(absoluteDocPath, '# cache test\n', 'utf8');
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('GET', '/api/taskforce/sync/workspace/documents', routes);
+        expect(match).toBeTruthy();
+        const req1 = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${workspaceId}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const res1 = createMockRes();
+        await match?.handler(req1, res1, {});
+        expect(res1.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const body1 = JSON.parse(String(res1.end.mock.calls.at(-1)?.[0] || '{}'));
+        const req2 = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${workspaceId}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const res2 = createMockRes();
+        await match?.handler(req2, res2, {});
+        expect(res2.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const body2 = JSON.parse(String(res2.end.mock.calls.at(-1)?.[0] || '{}'));
+        const firstDoc1 = (Array.isArray(body1?.documents) ? body1.documents : []).find((doc) => doc.path === relativeDocPath);
+        const firstDoc2 = (Array.isArray(body2?.documents) ? body2.documents : []).find((doc) => doc.path === relativeDocPath);
+        expect(firstDoc1?.content).toBe('# cache test\n');
+        expect(firstDoc2?.content).toBe('# cache test\n');
+        expect(firstDoc2?.updatedAt).toBe(firstDoc1?.updatedAt);
+        fs.writeFileSync(absoluteDocPath, '# cache test changed\n', 'utf8');
+        const req3 = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${workspaceId}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const res3 = createMockRes();
+        await match?.handler(req3, res3, {});
+        expect(res3.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const body3 = JSON.parse(String(res3.end.mock.calls.at(-1)?.[0] || '{}'));
+        const firstDoc3 = (Array.isArray(body3?.documents) ? body3.documents : []).find((doc) => doc.path === relativeDocPath);
+        expect(firstDoc3?.content).toBe('# cache test changed\n');
+    });
+    it('includes locally uploaded canonical markdown attachments in the workspace document snapshot', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-canonical-doc-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        const task = core.createTask({ title: 'Task with markdown attachment' }, { workspaceId });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const uploadMatch = matchRoute('POST', '/api/taskforce/context-upload', routes);
+        expect(uploadMatch).toBeTruthy();
+        const uploadReq = createMockReq('POST', '/api/taskforce/context-upload', {
+            file: `data:text/markdown;base64,${Buffer.from('# local attachment\n', 'utf8').toString('base64')}`,
+            originalName: 'local-notes.md',
+            taskId: task.id
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const uploadRes = createMockRes();
+        await uploadMatch?.handler(uploadReq, uploadRes, {});
+        expect(uploadRes.writeHead).toHaveBeenCalledWith(200, { 'Content-Type': 'application/json' });
+        const uploadBody = JSON.parse(String(uploadRes.end.mock.calls.at(-1)?.[0] || '{}'));
+        expect(String(uploadBody?.fsPath || '')).toContain(`workspaces/${workspaceId}/assets/documents/`);
+        const documentsMatch = matchRoute('GET', '/api/taskforce/sync/workspace/documents', routes);
+        expect(documentsMatch).toBeTruthy();
+        const req = createMockReq('GET', `/api/taskforce/sync/workspace/documents?workspaceId=${encodeURIComponent(workspaceId)}`, undefined, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await documentsMatch?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const body = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+        const relativeDocPath = String(uploadBody?.fsPath || '');
+        const doc = (Array.isArray(body?.documents) ? body.documents : []).find((entry) => entry.path === relativeDocPath);
+        expect(doc).toBeTruthy();
+        expect(doc.content).toBe('# local attachment\n');
+    });
+    it('converges task conflicts deterministically for equal timestamps regardless of apply order', async () => {
+        const applySequence = async (prefix, titlesInOrder) => {
+            const projectRoot = createIsolatedProjectRoot(prefix);
+            const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+            core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+            const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+            expect(match).toBeTruthy();
+            for (const title of titlesInOrder) {
+                const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+                    changes: [{
+                            op: 'upsert',
+                            archived: false,
+                            task: {
+                                id: 'task-concurrent-1',
+                                title,
+                                status: 'task',
+                                createdAt: '2026-02-27T00:00:00.000Z',
+                                updatedAt: '2026-02-27T00:00:00.000Z'
+                            }
+                        }]
+                }, { 'x-taskforce-workspace-id': workspaceId });
+                const res = createMockRes();
+                await match?.handler(req, res, {});
+                expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            }
+            return core.getTask('task-concurrent-1', workspaceId)?.title || null;
+        };
+        const orderAB = await applySequence('taskforce-sync-conflict-task-ab-', ['alpha-title', 'zeta-title']);
+        const orderBA = await applySequence('taskforce-sync-conflict-task-ba-', ['zeta-title', 'alpha-title']);
+        expect(orderAB).toBeTruthy();
+        expect(orderBA).toBe(orderAB);
+    });
+    it('converges document metadata conflicts deterministically for equal timestamps regardless of apply order', async () => {
+        const applySequence = async (prefix, contentsInOrder) => {
+            const projectRoot = createIsolatedProjectRoot(prefix);
+            const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+            core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+            const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+            expect(match).toBeTruthy();
+            const relativeDocPath = 'docs/conflict-doc.md';
+            const absoluteDocPath = path.join(core.getPaths().basePath, relativeDocPath);
+            for (const content of contentsInOrder) {
+                const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+                    changes: [{
+                            op: 'document-upsert',
+                            path: relativeDocPath,
+                            updatedAt: '2026-02-27T00:00:00.000Z',
+                            content
+                        }]
+                }, { 'x-taskforce-workspace-id': workspaceId });
+                const res = createMockRes();
+                await match?.handler(req, res, {});
+                expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            }
+            return fs.existsSync(absoluteDocPath) ? fs.readFileSync(absoluteDocPath, 'utf8') : '';
+        };
+        const orderAB = await applySequence('taskforce-sync-conflict-doc-ab-', ['doc-content-alpha', 'doc-content-zeta']);
+        const orderBA = await applySequence('taskforce-sync-conflict-doc-ba-', ['doc-content-zeta', 'doc-content-alpha']);
+        expect(orderAB).toBeTruthy();
+        expect(orderBA).toBe(orderAB);
+    });
+    it('returns 200 with skipped count when updateTask throws during apply-local (regression for Bug 1)', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-updatethrow-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        // Create the task first so the apply-local path takes the updateTask branch
+        core.createTask({
+            id: 'task-update-throws',
+            title: 'Original title',
+            status: 'task'
+        }, {
+            workspaceId,
+            allowClientProvidedId: true
+        });
+        // Stub updateTask to throw on this specific task id
+        const originalUpdateTask = core.updateTask.bind(core);
+        vi.spyOn(core, 'updateTask').mockImplementationOnce((...args) => {
+            if (args[0] === 'task-update-throws') {
+                throw new Error('Rule violation: cannot update task');
+            }
+            return originalUpdateTask(...args);
+        });
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'upsert',
+                    archived: false,
+                    task: {
+                        id: 'task-update-throws',
+                        title: 'Updated title from cloud',
+                        status: 'in-progress'
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const body = readJsonBody(res);
+        expect(body.result.skipped).toBeGreaterThanOrEqual(1);
+    });
+    it('preserves seeded first-class taxonomy state when apply-local receives a partial taxonomy payload', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-apply-taxonomy-partial-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+        core.updateTaxonomyState(buildSoftwareTaxonomyState(), workspaceId);
+        const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+            changes: [
+                {
+                    op: 'taxonomy-upsert',
+                    updatedAt: '2026-03-30T17:05:00.000Z',
+                    taxonomyState: {
+                        categories: [{ value: 'default', label: 'General', icon: 'Inbox' }],
+                        priorities: [
+                            { value: 1, label: 'Low', color: 'teal-500', icon: 'ArrowDown' },
+                            { value: 2, label: 'Medium', color: 'blue-500', icon: 'Minus' },
+                            { value: 3, label: 'High', color: 'amber-500', icon: 'ArrowUp' }
+                        ],
+                        taxonomies: []
+                    }
+                }
+            ]
+        }, { 'x-taskforce-workspace-id': workspaceId });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const state = core.getTaxonomyState(workspaceId);
+        expect((state.types || []).map((type) => type.value)).toEqual([
+            'feature',
+            'bug',
+            'chore',
+            'refactor',
+            'documentation'
+        ]);
+        expect((state.priorities || []).map((priority) => priority.value)).toEqual([1, 2, 3, 4]);
+    });
+    it('preserves seeded first-class taxonomy state when bootstrap-push receives a partial taxonomy payload', async () => {
+        const projectRoot = createIsolatedProjectRoot('taskforce-sync-bootstrap-taxonomy-partial-');
+        const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+        seedAuthenticatedWorkspace(core);
+        core.updateTaxonomyState(buildSoftwareTaxonomyState(), workspaceId);
+        const routes = createRoutes(core, { authConfig });
+        const match = matchRoute('POST', '/api/taskforce/sync/workspace/bootstrap-push', routes);
+        expect(match).toBeTruthy();
+        const req = createMockReq('POST', '/api/taskforce/sync/workspace/bootstrap-push', {
+            workspaceId,
+            tasks: [],
+            archived: [],
+            taxonomyState: {
+                categories: [{ value: 'default', label: 'General', icon: 'Inbox' }],
+                priorities: [
+                    { value: 1, label: 'Low', color: 'teal-500', icon: 'ArrowDown' },
+                    { value: 2, label: 'Medium', color: 'blue-500', icon: 'Minus' },
+                    { value: 3, label: 'High', color: 'amber-500', icon: 'ArrowUp' }
+                ],
+                taxonomies: []
+            }
+        }, { cookie: createAuthCookie(workspaceId) });
+        const res = createMockRes();
+        await match?.handler(req, res, {});
+        expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        const state = core.getTaxonomyState(workspaceId);
+        expect((state.types || []).map((type) => type.value)).toEqual([
+            'feature',
+            'bug',
+            'chore',
+            'refactor',
+            'documentation'
+        ]);
+        expect((state.priorities || []).map((priority) => priority.value)).toEqual([1, 2, 3, 4]);
+    });
+    it('converges taxonomy conflicts deterministically for equal timestamps regardless of apply order', async () => {
+        const applySequence = async (prefix, taxonomiesInOrder) => {
+            const projectRoot = createIsolatedProjectRoot(prefix);
+            const core = new TaskforceCore({ projectRoot, storagePath: '.taskforce' });
+            core.createWorkspace({ workspaceId, name: 'Local Active Workspace' });
+            const routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+            expect(match).toBeTruthy();
+            for (const taxonomies of taxonomiesInOrder) {
+                const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+                    changes: [{
+                            op: 'taxonomy-upsert',
+                            updatedAt: '2026-02-27T00:00:00.000Z',
+                            taxonomies
+                        }]
+                }, { 'x-taskforce-workspace-id': workspaceId });
+                const res = createMockRes();
+                await match?.handler(req, res, {});
+                expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            }
+            return core.getTaxonomies();
+        };
+        const alphaTaxonomies = [{ id: 'custom', label: 'Alpha', options: [], widgetType: 'select', isSystem: false, multiSelect: false }];
+        const zetaTaxonomies = [{ id: 'custom', label: 'Zeta', options: [], widgetType: 'select', isSystem: false, multiSelect: false }];
+        const orderAB = await applySequence('taskforce-sync-conflict-tax-ab-', [alphaTaxonomies, zetaTaxonomies]);
+        const orderBA = await applySequence('taskforce-sync-conflict-tax-ba-', [zetaTaxonomies, alphaTaxonomies]);
+        expect(Array.isArray(orderAB)).toBe(true);
+        expect(orderBA).toEqual(orderAB);
+    });
+});