@taskforcehq/taskforce 0.3.168

package/dist/server/routes.sync.d.ts

@@ -0,0 +1,17 @@
+import { IncomingMessage } from 'http';
+import { TaskforceCore } from '../core/Taskforce.js';
+import { RouteHandler, RouteContext } from './routes.js';
+import { resolveRequestAccess, createSessionTokenCookie } from './auth.js';
+import { isReservedWorkspaceId } from '../utils/workspaceIdentity.js';
+export interface SyncRouteDependencies {
+    addRoute: (method: string, path: string, handler: RouteHandler) => void;
+    core: TaskforceCore;
+    context: RouteContext;
+    auditAuthAction: (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
+    resolveErrorStatusCode: (error: unknown, fallback?: number) => number;
+    requestWorkspaceId: (req: IncomingMessage) => string | null;
+    resolveRequestAccess: typeof resolveRequestAccess;
+    isReservedWorkspaceId: typeof isReservedWorkspaceId;
+    createSessionTokenCookie: typeof createSessionTokenCookie;
+}
+export declare function registerSyncRoutes(deps: SyncRouteDependencies): void;

package/dist/server/routes.sync.integration.test.d.ts

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

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

@@ -0,0 +1,470 @@
+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';
+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;
+    };
+    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 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('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' });
+        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' });
+        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 = path.join(seedCore.getPaths().basePath, '.taskforce');
+        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('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' });
+        const now = new Date().toISOString();
+        seedCore.db.prepare('INSERT OR IGNORE INTO users (id, tenant_id, email, created_at, updated_at) VALUES (?, ?, ?, ?, ?)').run('integration-user', 'default', 'integration@test.com', now, now);
+        seedCore.createWorkspaceForUser({
+            userId: 'integration-user',
+            name: 'Local Active Workspace',
+            role: 'owner',
+            preferredWorkspaceId: workspaceId
+        });
+        const syncRoot = path.join(seedCore.getPaths().basePath, '.taskforce');
+        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('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' });
+        const now = new Date().toISOString();
+        seedCore.db.prepare('INSERT OR IGNORE INTO users (id, tenant_id, email, created_at, updated_at) VALUES (?, ?, ?, ?, ?)').run('integration-user', 'default', 'integration@test.com', now, now);
+        seedCore.createWorkspaceForUser({
+            userId: 'integration-user',
+            name: 'Local Active Workspace',
+            role: 'owner',
+            preferredWorkspaceId: workspaceId
+        });
+        const syncRoot = path.join(seedCore.getPaths().basePath, '.taskforce');
+        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('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('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 = path.join(core.getPaths().basePath, '.taskforce');
+        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');
+        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');
+        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');
+        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('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, '.taskforce', 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('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);
+    });
+});