@taskforcehq/taskforce 0.3.305 → 0.3.306

package/dist/server/routes.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { createRoutes, matchRoute, parseJsonBody } from './routes';
-import { createSessionTokenCookie } from './auth';
+import { createSessionTokenCookie, resolveRequestAccess } from './auth';
 import { TaskforceCore } from '../core/Taskforce';
 import { Readable, Writable } from 'stream';
 import * as fs from 'fs';
@@ -102,6 +102,11 @@ vi.mock('../core/Taskforce', () => {
             });
             listInitiatives = vi.fn().mockReturnValue([]);
             listWorkstreams = vi.fn().mockReturnValue([]);
+            listPlanningBootstrap = vi.fn().mockReturnValue({
+                initiatives: [],
+                workstreams: [],
+                workstreamTaskSummaries: []
+            });
             getInitiativeTemplates = vi.fn();
             createInitiativeFromTemplate = vi.fn();
             getCategories = vi.fn();
@@ -156,6 +161,9 @@ vi.mock('../core/Taskforce', () => {
             listWorkspaceUsers = vi.fn().mockReturnValue([]);
             listAssignableActors = vi.fn();
             listAiProfiles = vi.fn().mockReturnValue([]);
+            countAiProfileUsage = vi.fn().mockReturnValue({ used: 0, limit: null, remaining: null });
+            mergeAiProfiles = vi.fn();
+            archiveAiProfile = vi.fn();
             replaceWorkspaceUsersForSync = vi.fn().mockReturnValue([]);
             listDocumentReviewSessionsForSync = vi.fn().mockReturnValue([]);
             listDocumentReviewCommentsForSync = vi.fn().mockReturnValue([]);
@@ -235,6 +243,7 @@ vi.mock('../core/Taskforce', () => {
                     updatedAt: '2026-01-01T00:00:00.000Z'
                 }
             ]);
+            countSystemUsers = vi.fn().mockReturnValue(1);
             getSystemRole = vi.fn().mockReturnValue('user');
             getUserBetaAccess = vi.fn().mockReturnValue(true);
             setSystemRole = vi.fn().mockReturnValue(true);
@@ -411,7 +420,7 @@ vi.mock('../core/Taskforce', () => {
                     }
                 },
                 {
-                    featureKey: 'workspace.switching',
+                    featureKey: 'workspace.workspaces',
                     label: 'Workspaces',
                     description: 'Allow multiple workspaces with a configurable workspace limit.',
                     allowedAccessModes: ['enabled', 'disabled'],
@@ -624,6 +633,12 @@ describe('Server Routes', () => {
             if (typeof body === 'string') {
                 req.push(body);
             }
+            else if (Buffer.isBuffer(body)) {
+                req.push(body);
+            }
+            else if (body instanceof Uint8Array) {
+                req.push(Buffer.from(body));
+            }
             else {
                 req.push(body ? JSON.stringify(body) : null);
             }
@@ -700,6 +715,17 @@ describe('Server Routes', () => {
                     process.env.TASKFORCE_AUTH_EXPOSE_DEV_TOKENS = previous;
             }
         };
+        const createCloudAuthConfig = () => ({
+            runtimeMode: 'cloud',
+            enabled: true,
+            requiredForApi: true,
+            excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+            defaultRole: 'member',
+            defaultWorkspaceId: 'default',
+            sessionCookieName: 'taskforce_session',
+            sessionSecret: 'test-secret',
+            sessionTtlSeconds: 3600
+        });
         it('GET /api/taskforce/tasks should return tasks', async () => {
             const mockTasks = { tasks: [], config: {} };
             core.listTasks.mockReturnValue(mockTasks);
@@ -711,6 +737,30 @@ describe('Server Routes', () => {
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             expect(res.end).toHaveBeenCalledWith(JSON.stringify(mockTasks));
         });
+        it('GET /api/taskforce/planning/bootstrap should return lightweight planning bootstrap data', async () => {
+            const payload = {
+                initiatives: [{ id: 'initiative-1', title: 'Launch', description: null, createdAt: '2026-04-22T00:00:00.000Z' }],
+                workstreams: [{ id: 'workstream-1', title: 'Billing', description: null, createdAt: '2026-04-22T00:00:00.000Z' }],
+                workstreamTaskSummaries: [{
+                        workstreamId: 'workstream-1',
+                        taskCount: 2,
+                        completedTaskCount: 1,
+                        tasks: [
+                            { id: 'task-1', title: 'Draft copy', referenceNumber: 12, status: 'task' },
+                            { id: 'task-2', title: 'Review copy', referenceNumber: 13, status: 'done' }
+                        ]
+                    }]
+            };
+            core.listPlanningBootstrap.mockReturnValue(payload);
+            const match = matchRoute('GET', '/api/taskforce/planning/bootstrap', routes);
+            const req = createMockReq('GET', '/api/taskforce/planning/bootstrap');
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.listPlanningBootstrap).toHaveBeenCalledWith('default', expect.any(Object));
+            expect(res.setHeader).toHaveBeenCalledWith('Server-Timing', expect.stringContaining('planning-bootstrap'));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(JSON.stringify(payload));
+        });
         it('GET /mcp should return MCP JSON error instead of falling through when unauthenticated in cloud runtime', async () => {
             const match = matchRoute('GET', '/mcp', routes);
             const req = createMockReq('GET', '/mcp', undefined, {
@@ -2157,6 +2207,96 @@ describe('Server Routes', () => {
             expect(fetchMock).not.toHaveBeenCalled();
             vi.unstubAllGlobals();
         });
+        it('GET /api/taskforce/context/:filename should proxy R2 user avatars inline instead of redirecting', async () => {
+            const fetchMock = vi.fn().mockResolvedValue(new Response('avatar-bytes', {
+                status: 200,
+                headers: { 'Content-Type': 'image/webp' }
+            }));
+            vi.stubGlobal('fetch', fetchMock);
+            const routesWithStorage = createRoutes(core, {
+                objectStorage: {
+                    provider: 'r2',
+                    r2: {
+                        accountId: 'acct-1',
+                        bucket: 'taskforce-docs',
+                        endpoint: 'https://example.r2.cloudflarestorage.com',
+                        accessKeyId: 'access-key-1',
+                        secretAccessKey: 'secret-key-1',
+                        keyPrefix: 'taskforce',
+                        signedUploadTtlSeconds: 600,
+                        signedDownloadTtlSeconds: 300
+                    }
+                }
+            });
+            const encoded = encodeURIComponent('users/user-1/profile/avatar/avatar-draft-1-headshot.webp');
+            const match = matchRoute('GET', `/api/taskforce/context/${encoded}`, routesWithStorage);
+            const req = createMockReq('GET', `/api/taskforce/context/${encoded}`);
+            const res = createMockRes();
+            await match?.handler(req, res, { filename: encoded });
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.objectContaining({
+                'Content-Type': 'image/webp',
+                'Content-Disposition': 'inline'
+            }));
+            expect(String(res.getHeader('location') || '')).toBe('');
+            expect(res.__getBody()).toBe('avatar-bytes');
+            expect(String(fetchMock.mock.calls[0][0])).toContain('https://example.r2.cloudflarestorage.com/taskforce-docs/taskforce/users/user-1/profile/avatar/avatar-draft-1-headshot.webp');
+            vi.unstubAllGlobals();
+        });
+        it('GET /api/taskforce/context/:filename should proxy missing cloud-owned user avatars in local runtime', async () => {
+            const previousCloudProxyBaseUrl = process.env.TASKFORCE_CLOUD_PROXY_BASE_URL;
+            const previousClientId = process.env.TASKFORCE_CF_ACCESS_CLIENT_ID;
+            const previousClientSecret = process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET;
+            process.env.TASKFORCE_CLOUD_PROXY_BASE_URL = 'https://performance-app.taskforcehq.ai';
+            process.env.TASKFORCE_CF_ACCESS_CLIENT_ID = 'cf-client-id';
+            process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET = 'cf-client-secret';
+            const fetchMock = vi.fn().mockResolvedValue(new Response('avatar-bytes', {
+                status: 200,
+                headers: {
+                    'Content-Type': 'image/webp',
+                    'Cache-Control': 'private, max-age=60'
+                }
+            }));
+            vi.stubGlobal('fetch', fetchMock);
+            try {
+                const relativePath = 'users/user-1/profile/avatar/avatar-draft-1-headshot.webp';
+                const encoded = encodeURIComponent(relativePath);
+                const match = matchRoute('GET', `/api/taskforce/context/${encoded}`, routes);
+                const req = createMockReq('GET', `/api/taskforce/context/${encoded}`, undefined, {
+                    host: 'localhost:5174',
+                    cookie: 'taskforce_session=session-1',
+                    accept: 'image/webp'
+                });
+                const res = createMockRes();
+                await match?.handler(req, res, { filename: encoded });
+                expect(fetchMock).toHaveBeenCalledWith(`https://performance-app.taskforcehq.ai/api/taskforce/context/${encoded}`, expect.objectContaining({
+                    method: 'GET',
+                    headers: expect.any(Headers)
+                }));
+                const proxiedHeaders = fetchMock.mock.calls[0][1].headers;
+                expect(proxiedHeaders.get('cookie')).toBe('taskforce_session=session-1');
+                expect(proxiedHeaders.get('CF-Access-Client-Id')).toBe('cf-client-id');
+                expect(proxiedHeaders.get('CF-Access-Client-Secret')).toBe('cf-client-secret');
+                expect(res.writeHead).toHaveBeenCalledWith(200, expect.objectContaining({
+                    'content-type': 'image/webp'
+                }));
+                expect(res.__getBody()).toBe('avatar-bytes');
+            }
+            finally {
+                vi.unstubAllGlobals();
+                if (previousCloudProxyBaseUrl === undefined)
+                    delete process.env.TASKFORCE_CLOUD_PROXY_BASE_URL;
+                else
+                    process.env.TASKFORCE_CLOUD_PROXY_BASE_URL = previousCloudProxyBaseUrl;
+                if (previousClientId === undefined)
+                    delete process.env.TASKFORCE_CF_ACCESS_CLIENT_ID;
+                else
+                    process.env.TASKFORCE_CF_ACCESS_CLIENT_ID = previousClientId;
+                if (previousClientSecret === undefined)
+                    delete process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET;
+                else
+                    process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET = previousClientSecret;
+            }
+        });
         it('GET /api/taskforce/context/:filename should proxy inline R2 markdown documents instead of redirecting', async () => {
             const fetchMock = vi.fn().mockResolvedValue({
                 status: 200,
@@ -3447,6 +3587,53 @@ describe('Server Routes', () => {
             fs.rmSync(dbRoot, { recursive: true, force: true });
             fs.rmSync(tmpRoot, { recursive: true, force: true });
         });
+        it('GET /api/taskforce/documents should exclude raw .taskforce/docs markdown files from the document manager', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-exclude-raw-docs-'));
+            const basePath = path.join(tmpRoot, '.taskforce');
+            fs.mkdirSync(path.join(basePath, 'docs'), { recursive: true });
+            fs.writeFileSync(path.join(basePath, 'docs', 'legacy-plan.md'), '# legacy\n', 'utf8');
+            core.getPaths.mockReturnValue({
+                projectRoot: tmpRoot,
+                basePath,
+            });
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            store.upsertAsset({
+                assetId: 'asset-doc-local-2',
+                workspaceId: 'default',
+                kind: 'document',
+                originalFilename: 'managed-plan.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'local',
+                storageKey: 'workspaces/default/assets/documents/asset-doc-local-2-managed-plan.md',
+                contentSha256: 'sha-doc-local-2',
+                sizeBytes: 99,
+                documentId: 'doc-local-2',
+                version: 1,
+                updatedAt: '2026-04-19T12:00:00.000Z'
+            });
+            const routesWithDb = createRoutes(core);
+            const match = matchRoute('GET', '/api/taskforce/documents', routesWithDb);
+            const req = createMockReq('GET', '/api/taskforce/documents', undefined, {
+                'x-taskforce-workspace-id': 'default',
+                'x-taskforce-runtime-mode': 'local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(Array.isArray(payload.documents)).toBe(true);
+            expect(payload.documents).toHaveLength(1);
+            expect(payload.documents[0]).toEqual(expect.objectContaining({
+                id: 'asset-doc-local-2',
+                assetId: 'asset-doc-local-2',
+                fsPath: 'workspaces/default/assets/documents/asset-doc-local-2-managed-plan.md',
+                attachmentState: 'unattached'
+            }));
+            expect(payload.documents.some((doc) => String(doc.fsPath || '').includes('docs/legacy-plan.md'))).toBe(false);
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
         it('GET /api/taskforce/documents should mark canonical docs without links as unattached', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-unattached-local-'));
             core.getPaths.mockReturnValue({
@@ -3543,6 +3730,111 @@ describe('Server Routes', () => {
             fs.rmSync(dbRoot, { recursive: true, force: true });
             fs.rmSync(tmpRoot, { recursive: true, force: true });
         });
+        it('GET /api/taskforce/documents should count non-task links in attachment metadata while only surfacing task titles for task links', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-generic-links-'));
+            core.getPaths.mockReturnValue({
+                projectRoot: tmpRoot,
+                basePath: path.join(tmpRoot, '.taskforce'),
+            });
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            store.upsertAsset({
+                assetId: 'asset-doc-generic-link-1',
+                workspaceId: 'default',
+                kind: 'document',
+                originalFilename: 'shared-notes.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'local',
+                storageKey: 'workspaces/default/assets/documents/asset-doc-generic-link-1-shared-notes.md',
+                contentSha256: 'sha-doc-generic-link-1',
+                sizeBytes: 64,
+                documentId: 'doc-generic-link-1',
+                version: 1,
+                updatedAt: '2026-03-18T13:30:00.000Z'
+            });
+            store.upsertLink({
+                workspaceId: 'default',
+                assetId: 'asset-doc-generic-link-1',
+                targetType: 'initiative',
+                targetId: 'initiative-1',
+                role: 'attachment'
+            });
+            const routesWithDb = createRoutes(core);
+            const match = matchRoute('GET', '/api/taskforce/documents', routesWithDb);
+            const req = createMockReq('GET', '/api/taskforce/documents', undefined, {
+                'x-taskforce-workspace-id': 'default',
+                'x-taskforce-runtime-mode': 'local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.documents).toEqual([
+                expect.objectContaining({
+                    id: 'asset-doc-generic-link-1',
+                    assetId: 'asset-doc-generic-link-1',
+                    attachmentCount: 1,
+                    attachmentState: 'attached',
+                    taskId: null
+                })
+            ]);
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
+        it('POST /api/taskforce/documents/:assetId/attach should attach a canonical document to a task target', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-attach-task-'));
+            core.getPaths.mockReturnValue({
+                projectRoot: tmpRoot,
+                basePath: path.join(tmpRoot, '.taskforce'),
+            });
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            store.upsertAsset({
+                assetId: 'asset-doc-attach-route-1',
+                workspaceId: 'default',
+                kind: 'document',
+                logicalName: 'Attach Me',
+                originalFilename: 'attach-me.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'local',
+                storageKey: 'workspaces/default/assets/documents/asset-doc-attach-route-1-attach-me.md',
+                contentSha256: 'sha-doc-attach-route-1',
+                sizeBytes: 28,
+                documentId: 'doc-attach-route-1',
+                version: 1,
+                updatedAt: '2026-03-18T13:30:00.000Z'
+            });
+            core.getTask.mockImplementation((id) => id === 'task-attach-1'
+                ? { id: 'task-attach-1', title: 'Attach target', attachments: [] }
+                : null);
+            const routesWithDb = createRoutes(core);
+            const match = matchRoute('POST', '/api/taskforce/documents/asset-doc-attach-route-1/attach', routesWithDb);
+            const req = createMockReq('POST', '/api/taskforce/documents/asset-doc-attach-route-1/attach', {
+                targetType: 'task',
+                targetId: 'task-attach-1',
+            }, {
+                'x-taskforce-workspace-id': 'default'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { assetId: 'asset-doc-attach-route-1' });
+            expect(res.writeHead).toHaveBeenCalledWith(200, { 'Content-Type': 'application/json' });
+            expect(core.updateTask).toHaveBeenCalledWith('task-attach-1', expect.objectContaining({
+                attachments: [
+                    expect.objectContaining({
+                        assetId: 'asset-doc-attach-route-1',
+                        taskId: 'task-attach-1',
+                        path: '/api/taskforce/documents/asset-doc-attach-route-1/content',
+                    })
+                ]
+            }), 'default', expect.objectContaining({
+                actorRef: 'user',
+                saveSource: 'manual',
+            }));
+            expect(core.notifyDocumentMetadataMutation).toHaveBeenCalledWith('default', ['workspaces/default/assets/documents/asset-doc-attach-route-1-attach-me.md'], 'upsert');
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
         it('GET /api/taskforce/documents should normalize readable names and attachment metadata for sparse canonical assets', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-normalized-cloud-'));
             core.getPaths.mockReturnValue({
@@ -4559,6 +4851,40 @@ describe('Server Routes', () => {
             expect(payload.inviteeKind).toBe('existing_user');
             expect(payload.passwordRequired).toBe(false);
         });
+        it('POST /api/taskforce/auth/invite/accept should preserve the created identity in the session cookie', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.acceptInviteWithToken.mockReturnValueOnce({
+                userId: 'u1',
+                email: 'u1@example.com',
+                workspaceId: 'workspace-1',
+                role: 'member',
+                identityId: 'identity-password-u1'
+            });
+            const match = matchRoute('POST', '/api/taskforce/auth/invite/accept', routes);
+            const req = createMockReq('POST', '/api/taskforce/auth/invite/accept', { token: 'accept-token', password: 'password123' }, {
+                'x-taskforce-runtime-mode': 'cloud',
+                host: 'localhost'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const setCookie = res.setHeader.mock.calls.find(([name]) => name === 'Set-Cookie')?.[1];
+            expect(typeof setCookie).toBe('string');
+            const cookieReq = createMockReq('GET', '/api/taskforce/me', undefined, { cookie: setCookie });
+            const access = resolveRequestAccess(cookieReq, authConfig);
+            expect(access.identityId).toBe('identity-password-u1');
+            expect(access.userId).toBe('u1');
+        });
         it('POST /api/taskforce/auth/invite/accept should return expired code and audit action', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -4649,7 +4975,8 @@ describe('Server Routes', () => {
             const cookie = createSessionTokenCookie('session-join', authConfig, {
                 userId: 'u1',
                 role: 'member',
-                workspaceId: 'workspace-1'
+                workspaceId: 'workspace-1',
+                identityId: 'identity-u1'
             });
             const match = matchRoute('POST', '/api/taskforce/auth/invite/join', routes);
             const req = createMockReq('POST', '/api/taskforce/auth/invite/join', { token: 'join-token' }, {
@@ -4663,6 +4990,11 @@ describe('Server Routes', () => {
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.workspaceId).toBe('workspace-1');
+            const setCookie = res.setHeader.mock.calls.find(([name]) => name === 'Set-Cookie')?.[1];
+            expect(typeof setCookie).toBe('string');
+            const cookieReq = createMockReq('GET', '/api/taskforce/me', undefined, { cookie: setCookie });
+            const access = resolveRequestAccess(cookieReq, authConfig);
+            expect(access.identityId).toBe('identity-u1');
         });
         it('POST /api/taskforce/auth/login should auto-verify bootstrap admin and sign in', async () => {
             const authConfig = {
@@ -4991,6 +5323,7 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.listUserWorkspaces).toHaveBeenCalledWith('user-1');
+            expect(res.setHeader).toHaveBeenCalledWith('Server-Timing', expect.stringContaining('workspaces'));
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"workspace-2"'));
         });
@@ -5884,6 +6217,9 @@ describe('Server Routes', () => {
             await match?.handler(req, res, {});
             const payloadRaw = res.end.mock.calls[0]?.[0];
             const payload = JSON.parse(String(payloadRaw || '{}'));
+            expect(payload.knownPaths).toEqual([
+                'workspaces/workspace-local/assets/documents/asset-doc-snapshot-1-sync-notes.md'
+            ]);
             expect(payload.documents).toEqual(expect.arrayContaining([
                 expect.objectContaining({
                     path: 'workspaces/workspace-local/assets/documents/asset-doc-snapshot-1-sync-notes.md',
@@ -5898,7 +6234,56 @@ describe('Server Routes', () => {
             expect(String(payload.fingerprint || '')).toContain('asset-doc-snapshot-1');
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
-        it('GET /api/taskforce/sync/workspace/documents should include docs folder markdown files without canonical asset metadata', async () => {
+        it('GET /api/taskforce/sync/workspace/documents should retain canonical knownPaths even when content is temporarily unreadable', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-documents-known-paths-'));
+            const projectRoot = fs.realpathSync(tmpRoot);
+            const basePath = path.join(tmpRoot, '.taskforce');
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            store.upsertAsset({
+                assetId: 'asset-doc-known-path-1',
+                workspaceId: 'workspace-local',
+                kind: 'document',
+                originalFilename: 'missing-content.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'local',
+                storageKey: 'workspaces/workspace-local/assets/documents/asset-doc-known-path-1-missing-content.md',
+                contentSha256: 'missing-content-hash',
+                sizeBytes: 17,
+                documentId: 'doc-known-path-1',
+                version: 1,
+                isLatest: true,
+                createdAt: '2026-03-17T09:00:00.000Z',
+                updatedAt: '2026-03-17T10:00:00.000Z'
+            });
+            store.upsertLink({
+                workspaceId: 'workspace-local',
+                assetId: 'asset-doc-known-path-1',
+                taskId: 'task-1',
+                role: 'attachment'
+            });
+            core.getPaths.mockReturnValue({
+                projectRoot,
+                basePath,
+            });
+            core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            const match = matchRoute('GET', '/api/taskforce/sync/workspace/documents', routes);
+            const req = createMockReq('GET', '/api/taskforce/sync/workspace/documents?workspaceId=workspace-local', undefined, {
+                'x-taskforce-workspace-id': 'workspace-local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payloadRaw = res.end.mock.calls[0]?.[0];
+            const payload = JSON.parse(String(payloadRaw || '{}'));
+            expect(payload.documents).toEqual([]);
+            expect(payload.knownPaths).toEqual([
+                'workspaces/workspace-local/assets/documents/asset-doc-known-path-1-missing-content.md'
+            ]);
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+        });
+        it('GET /api/taskforce/sync/workspace/documents should exclude docs folder markdown files that are not canonical assets', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-documents-legacy-ignore-'));
             const projectRoot = fs.realpathSync(tmpRoot);
             const basePath = path.join(tmpRoot, '.taskforce');
@@ -5923,12 +6308,7 @@ describe('Server Routes', () => {
             const payloadRaw = res.end.mock.calls[0]?.[0];
             const payload = JSON.parse(String(payloadRaw || '{}'));
             expect(Array.isArray(payload.documents)).toBe(true);
-            expect(payload.documents).toEqual([
-                expect.objectContaining({
-                    path: 'docs/legacy-notes.md',
-                    content: '# legacy\n'
-                })
-            ]);
+            expect(payload.documents).toEqual([]);
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
         it('GET /api/taskforce/sync/workspace/document-reviews should include document review sessions for the requested workspace', async () => {
@@ -7086,7 +7466,7 @@ describe('Server Routes', () => {
                 task: expect.objectContaining({ id: 'task-b' })
             }));
         });
-        it('GET /api/taskforce/sync/workspace/pull should reject unauthorized workspace override', async () => {
+        it('GET /api/taskforce/sync/workspace/pull should reject an invalid sync cursor instead of replaying from the beginning', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
                 enabled: true,
@@ -7099,45 +7479,149 @@ describe('Server Routes', () => {
                 sessionTtlSeconds: 3600
             };
             routes = createRoutes(core, { authConfig });
-            const cookie = createSessionTokenCookie('session-sync-pull-forbidden', authConfig, {
+            core.listUserWorkspaces.mockReturnValue([{ id: 'workspace-1', slug: 'workspace-1', name: 'Workspace 1', description: null, role: 'owner', status: 'active', betaAccess: true }]);
+            const cookie = createSessionTokenCookie('session-sync-pull-invalid-cursor', authConfig, {
                 role: 'owner',
-                workspaceId: 'workspace-cloud-selected',
+                workspaceId: 'workspace-1',
                 userId: 'user-1'
             });
-            core.listUserWorkspaces.mockReturnValueOnce([
-                {
-                    id: 'workspace-a',
-                    slug: 'workspace-a',
-                    name: 'Workspace A',
-                    description: null,
-                    role: 'owner',
-                    status: 'active',
-                    betaAccess: true
-                }
-            ]);
             const match = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
-            const req = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-denied', undefined, { cookie });
+            const req = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-1&limit=10&cursor=not-a-real-cursor', undefined, { cookie });
             const res = createMockRes();
             await match?.handler(req, res, {});
-            expect(res.writeHead).toHaveBeenCalledWith(403, expect.any(Object));
-            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('WORKSPACE_ACCESS_DENIED'));
+            expect(core.listTasks).not.toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"code":"INVALID_SYNC_CURSOR"'));
             expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
-                action: 'sync-workspace-pull-forbidden',
-                details: { requestedWorkspaceId: 'workspace-denied' }
+                action: 'sync-workspace-pull-invalid-cursor'
             }));
         });
-        it('POST /api/taskforce/sync/workspace/apply-local should apply deltas when auth is enabled in local runtime', async () => {
-            core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
-            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: [
-                    { op: 'upsert', archived: false, task: { id: 'task-1', title: 'Task 1' } },
-                    { op: 'delete', taskId: 'task-2' }
-                ]
-            }, {
-                'x-taskforce-workspace-id': 'workspace-local'
-            });
+        it('GET /api/taskforce/sync/workspace/pull should ignore cursors during repair', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([{ id: 'workspace-1', slug: 'workspace-1', name: 'Workspace 1', description: null, role: 'owner', status: 'active', betaAccess: true }]);
+            core.listTasks.mockReturnValue({
+                tasks: [
+                    { id: 'task-repair-1', title: 'Repair me', createdAt: '2026-02-19T16:00:00.000Z', updatedAt: '2026-02-19T16:10:00.000Z' }
+                ]
+            });
+            core.listArchive.mockReturnValue({ archived: [] });
+            const cookie = createSessionTokenCookie('session-sync-pull-repair-cursor', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            const match = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+            const req = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-1&limit=10&cursor=not-a-real-cursor&repair=1', undefined, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(core.listTasks).toHaveBeenCalled();
+            const body = JSON.parse(String(res.end.mock.calls[0]?.[0] || '{}'));
+            expect(body.changes).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    op: 'upsert',
+                    task: expect.objectContaining({ id: 'task-repair-1' })
+                })
+            ]));
+        });
+        it('GET /api/taskforce/sync/workspace/pull should still return success when success audit throws', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValueOnce([{ id: 'workspace-1', slug: 'workspace-1', name: 'Workspace 1', description: null, role: 'owner', status: 'active', betaAccess: true }]);
+            const cookie = createSessionTokenCookie('session-sync-pull-audit-throw', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            const originalAddAdminAuditLog = core.addAdminAuditLog.getMockImplementation();
+            core.addAdminAuditLog.mockImplementation((entry) => {
+                if (entry?.action === 'sync-workspace-pull-success') {
+                    throw new Error('audit unavailable');
+                }
+                return originalAddAdminAuditLog ? originalAddAdminAuditLog(entry) : undefined;
+            });
+            const match = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+            const req = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-1&limit=10', undefined, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledTimes(1);
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
+        });
+        it('GET /api/taskforce/sync/workspace/pull should reject unauthorized workspace override', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            const cookie = createSessionTokenCookie('session-sync-pull-forbidden', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-cloud-selected',
+                userId: 'user-1'
+            });
+            core.listUserWorkspaces.mockReturnValueOnce([
+                {
+                    id: 'workspace-a',
+                    slug: 'workspace-a',
+                    name: 'Workspace A',
+                    description: null,
+                    role: 'owner',
+                    status: 'active',
+                    betaAccess: true
+                }
+            ]);
+            const match = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+            const req = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-denied', undefined, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(403, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('WORKSPACE_ACCESS_DENIED'));
+            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'sync-workspace-pull-forbidden',
+                details: { requestedWorkspaceId: 'workspace-denied' }
+            }));
+        });
+        it('POST /api/taskforce/sync/workspace/apply-local should apply deltas when auth is enabled in local runtime', async () => {
+            core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
+            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: [
+                    { op: 'upsert', archived: false, task: { id: 'task-1', title: 'Task 1' } },
+                    { op: 'delete', taskId: 'task-2' }
+                ]
+            }, {
+                'x-taskforce-workspace-id': 'workspace-local'
+            });
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.deleteTaskForSync).toHaveBeenCalledWith('task-2', 'workspace-local', { persistBackup: false });
@@ -7147,6 +7631,53 @@ describe('Server Routes', () => {
             }), 'workspace-local');
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
+        it('POST /api/taskforce/sync/workspace/apply-local should still return success when success sync telemetry throws after apply', async () => {
+            core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
+            routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            core.recordSyncEvent.mockImplementationOnce(() => {
+                throw new Error('telemetry unavailable');
+            });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+            const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+                changes: [
+                    { op: 'upsert', archived: false, task: { id: 'task-1', title: 'Task 1' } }
+                ]
+            }, {
+                'x-taskforce-workspace-id': 'workspace-local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledTimes(1);
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
+        });
+        it('POST /api/taskforce/sync/workspace/apply-local should still return error response when failure-path telemetry throws', async () => {
+            core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
+            routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            core.applyWorkspaceSyncSnapshot.mockImplementationOnce(() => {
+                throw new Error('apply failed');
+            });
+            core.recordSyncEvent.mockImplementationOnce(() => {
+                throw new Error('telemetry unavailable');
+            });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+            const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+                changes: [
+                    { op: 'upsert', archived: false, task: { id: 'task-1', title: 'Task 1' } }
+                ]
+            }, {
+                'x-taskforce-workspace-id': 'workspace-local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+            expect(res.end).toHaveBeenCalledTimes(1);
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":false'));
+        });
         it('POST /api/taskforce/sync/workspace/apply-local should apply document review session upserts and deletes', async () => {
             core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
             routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
@@ -7891,7 +8422,7 @@ describe('Server Routes', () => {
             ]);
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
-        it('POST /api/taskforce/sync/workspace/apply-local should preserve document references during normal sync when content is unchanged', async () => {
+        it('POST /api/taskforce/sync/workspace/apply-local should adopt cloud document references during normal sync even when content is unchanged', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-apply-doc-metadata-'));
             const projectRoot = fs.realpathSync(tmpRoot);
             const basePath = path.join(tmpRoot, '.taskforce');
@@ -7945,7 +8476,7 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(store.get('asset-sync-doc-meta-1', 'workspace-local')).toEqual(expect.objectContaining({
-                referenceNumber: 9
+                referenceNumber: 42
             }));
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
@@ -8008,7 +8539,7 @@ describe('Server Routes', () => {
             }));
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
-        it('POST /api/taskforce/sync/workspace/apply-local should preserve image references during normal sync when content is unchanged', async () => {
+        it('POST /api/taskforce/sync/workspace/apply-local should adopt cloud image references during normal sync even when content is unchanged', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-apply-image-metadata-'));
             const projectRoot = fs.realpathSync(tmpRoot);
             const basePath = path.join(tmpRoot, '.taskforce');
@@ -8060,7 +8591,7 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(store.get('asset-sync-image-meta-1', 'workspace-local')).toEqual(expect.objectContaining({
-                referenceNumber: 9
+                referenceNumber: 42
             }));
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
@@ -8387,7 +8918,7 @@ describe('Server Routes', () => {
                 action: 'sync-workspace-push-idempotent-replay'
             }));
         });
-        it('POST /api/taskforce/sync/workspace/push should persist synced cloud attachments into R2-backed canonical assets', async () => {
+        it('POST /api/taskforce/sync/workspace/push should still return success when idempotency persistence fails after apply', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
                 enabled: true,
@@ -8399,109 +8930,307 @@ describe('Server Routes', () => {
                 sessionSecret: 'test-secret',
                 sessionTtlSeconds: 3600
             };
-            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
-            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-push-r2-'));
-            core.getPaths.mockReturnValue({
-                projectRoot: tmpRoot,
-                basePath: path.join(tmpRoot, '.taskforce')
-            });
-            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
-            core.getTenantId = vi.fn().mockReturnValue('default');
+            routes = createRoutes(core, { authConfig });
             core.listUserWorkspaces.mockReturnValue([{ id: 'workspace-1', slug: 'workspace-1', name: 'Workspace 1', description: null, role: 'owner', status: 'active', betaAccess: true }]);
-            core.applyWorkspaceSyncSnapshot.mockReturnValue({
-                total: 0,
-                created: 0,
+            const cookie = createSessionTokenCookie('session-sync-push-idempotency-write-fail', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            core.applyWorkspaceSyncSnapshot.mockReturnValueOnce({
+                total: 1,
+                created: 1,
                 updated: 0,
                 archived: 0,
                 unarchived: 0,
                 skipped: 0
             });
-            const fetchMock = vi.fn().mockResolvedValue({
-                ok: true,
-                status: 200,
-                statusText: 'OK',
-                headers: new Headers(),
-                text: async () => '',
-                json: async () => ({})
-            });
-            vi.stubGlobal('fetch', fetchMock);
-            routes = createRoutes(core, {
-                authConfig,
-                objectStorage: {
-                    provider: 'r2',
-                    r2: {
-                        accountId: 'acct-1',
-                        bucket: 'taskforce-perf-assets',
-                        endpoint: 'https://acct-1.r2.cloudflarestorage.com',
-                        accessKeyId: 'access-key-1',
-                        secretAccessKey: 'secret-key-1',
-                        keyPrefix: '',
-                        signedUploadTtlSeconds: 600,
-                        signedDownloadTtlSeconds: 300
-                    }
-                }
-            });
-            const cookie = createSessionTokenCookie('session-sync-push-r2', authConfig, {
-                role: 'owner',
-                workspaceId: 'workspace-1',
-                userId: 'user-1'
+            core.writePushIdempotency.mockImplementationOnce(() => {
+                throw new Error('disk full');
             });
-            const markdownPath = 'workspaces/workspace-1/assets/documents/asset-doc-sync-1-plan.md';
-            const imagePath = 'workspaces/workspace-1/assets/images/asset-image-sync-1-proof.png';
             const match = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
             const req = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
                 workspaceId: 'workspace-1',
+                idempotencyKey: 'push-idempotency-write-fail-1',
                 changes: [
-                    {
-                        op: 'document-upsert',
-                        path: markdownPath,
-                        updatedAt: '2026-03-18T23:20:00.000Z',
-                        content: '# Plan',
-                        assetId: 'asset-doc-sync-1',
-                        documentId: 'doc-sync-1',
-                        taskId: 'task-sync-1',
-                        originalFilename: 'plan.md',
-                        linkRole: 'attachment'
-                    },
-                    {
-                        op: 'asset-upsert',
-                        path: imagePath,
-                        updatedAt: '2026-03-18T23:20:01.000Z',
-                        contentBase64: Buffer.from('png-bytes').toString('base64'),
-                        assetId: 'asset-image-sync-1',
-                        kind: 'image',
-                        mimeType: 'image/png',
-                        taskId: 'task-sync-1',
-                        originalFilename: 'proof.png',
-                        linkRole: 'image'
-                    }
+                    { op: 'upsert', task: { id: 'task-1', title: 'Task 1' }, archived: false }
                 ]
             }, { cookie });
             const res = createMockRes();
             await match?.handler(req, res, {});
+            expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledTimes(1);
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
-            expect(fetchMock).toHaveBeenCalledTimes(2);
-            const docAsset = store.getByStorageKey(markdownPath, 'workspace-1');
-            const imageAsset = store.getByStorageKey(imagePath, 'workspace-1');
-            expect(docAsset).toEqual(expect.objectContaining({
-                assetId: 'asset-doc-sync-1',
-                storageProvider: 'r2',
-                storageKey: markdownPath
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
+            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'sync-workspace-push-idempotency-write-failed'
             }));
-            expect(imageAsset).toEqual(expect.objectContaining({
-                assetId: 'asset-image-sync-1',
-                storageProvider: 'r2',
-                storageKey: imagePath
+            expect(core.recordSyncEvent).toHaveBeenCalledWith('workspace-1', expect.objectContaining({
+                eventType: 'push',
+                status: 'success'
             }));
-            expect(store.listLinksForTask('task-sync-1', 'workspace-1')).toEqual(expect.arrayContaining([
-                expect.objectContaining({ assetId: 'asset-doc-sync-1', role: 'attachment', deletedAt: null }),
-                expect.objectContaining({ assetId: 'asset-image-sync-1', role: 'image', deletedAt: null })
-            ]));
-            vi.unstubAllGlobals();
-            fs.rmSync(tmpRoot, { recursive: true, force: true });
-            fs.rmSync(dbRoot, { recursive: true, force: true });
         });
-        it('POST /api/taskforce/sync/workspace/push should audit unauthorized access', async () => {
+        it('POST /api/taskforce/sync/workspace/push should still return success when applied-task readback fails after apply', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([{ id: 'workspace-1', slug: 'workspace-1', name: 'Workspace 1', description: null, role: 'owner', status: 'active', betaAccess: true }]);
+            const cookie = createSessionTokenCookie('session-sync-push-upsert-echo-fail', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            core.applyWorkspaceSyncSnapshot.mockReturnValueOnce({
+                total: 1,
+                created: 1,
+                updated: 0,
+                archived: 0,
+                unarchived: 0,
+                skipped: 0
+            });
+            core.getTask.mockImplementationOnce(() => {
+                throw new Error('readback unavailable');
+            });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+            const req = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+                workspaceId: 'workspace-1',
+                idempotencyKey: 'push-upsert-echo-fail-1',
+                changes: [
+                    { op: 'upsert', task: { id: 'task-1', title: 'Task 1' }, archived: false }
+                ]
+            }, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+            expect(payload.success).toBe(true);
+            expect(payload.appliedTaskUpserts).toEqual([]);
+            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'sync-workspace-push-upsert-echo-failed'
+            }));
+            expect(core.recordSyncEvent).toHaveBeenCalledWith('workspace-1', expect.objectContaining({
+                eventType: 'push',
+                status: 'success'
+            }));
+        });
+        it('POST /api/taskforce/sync/workspace/push should still return success when success-path audit logging throws after apply', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([{ id: 'workspace-1', slug: 'workspace-1', name: 'Workspace 1', description: null, role: 'owner', status: 'active', betaAccess: true }]);
+            const cookie = createSessionTokenCookie('session-sync-push-success-audit-fail', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            core.applyWorkspaceSyncSnapshot.mockReturnValueOnce({
+                total: 1,
+                created: 1,
+                updated: 0,
+                archived: 0,
+                unarchived: 0,
+                skipped: 0
+            });
+            const originalAddAdminAuditLog = core.addAdminAuditLog.getMockImplementation();
+            core.addAdminAuditLog.mockImplementation((entry) => {
+                if (entry?.action === 'sync-workspace-push-success') {
+                    throw new Error('audit unavailable');
+                }
+                return originalAddAdminAuditLog ? originalAddAdminAuditLog(entry) : undefined;
+            });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+            const req = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+                workspaceId: 'workspace-1',
+                idempotencyKey: 'push-success-audit-fail-1',
+                changes: [
+                    { op: 'upsert', task: { id: 'task-1', title: 'Task 1' }, archived: false }
+                ]
+            }, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledTimes(1);
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
+            expect(core.recordSyncEvent).toHaveBeenCalledWith('workspace-1', expect.objectContaining({
+                eventType: 'push',
+                status: 'success'
+            }));
+        });
+        it('POST /api/taskforce/sync/workspace/push should still return error response when failure-path telemetry throws', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([{ id: 'workspace-1', slug: 'workspace-1', name: 'Workspace 1', description: null, role: 'owner', status: 'active', betaAccess: true }]);
+            const cookie = createSessionTokenCookie('session-sync-push-failure-telemetry-throw', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            core.applyWorkspaceSyncSnapshot.mockImplementationOnce(() => {
+                throw new Error('apply failed');
+            });
+            core.recordSyncEvent.mockImplementationOnce(() => {
+                throw new Error('telemetry unavailable');
+            });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+            const req = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+                workspaceId: 'workspace-1',
+                changes: [
+                    { op: 'upsert', task: { id: 'task-1', title: 'Task 1' }, archived: false }
+                ]
+            }, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+            expect(res.end).toHaveBeenCalledTimes(1);
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":false'));
+        });
+        it('POST /api/taskforce/sync/workspace/push should persist synced cloud attachments into R2-backed canonical assets', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-push-r2-'));
+            core.getPaths.mockReturnValue({
+                projectRoot: tmpRoot,
+                basePath: path.join(tmpRoot, '.taskforce')
+            });
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            core.listUserWorkspaces.mockReturnValue([{ id: 'workspace-1', slug: 'workspace-1', name: 'Workspace 1', description: null, role: 'owner', status: 'active', betaAccess: true }]);
+            core.applyWorkspaceSyncSnapshot.mockReturnValue({
+                total: 0,
+                created: 0,
+                updated: 0,
+                archived: 0,
+                unarchived: 0,
+                skipped: 0
+            });
+            const fetchMock = vi.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: 'OK',
+                headers: new Headers(),
+                text: async () => '',
+                json: async () => ({})
+            });
+            vi.stubGlobal('fetch', fetchMock);
+            routes = createRoutes(core, {
+                authConfig,
+                objectStorage: {
+                    provider: 'r2',
+                    r2: {
+                        accountId: 'acct-1',
+                        bucket: 'taskforce-perf-assets',
+                        endpoint: 'https://acct-1.r2.cloudflarestorage.com',
+                        accessKeyId: 'access-key-1',
+                        secretAccessKey: 'secret-key-1',
+                        keyPrefix: '',
+                        signedUploadTtlSeconds: 600,
+                        signedDownloadTtlSeconds: 300
+                    }
+                }
+            });
+            const cookie = createSessionTokenCookie('session-sync-push-r2', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            const markdownPath = 'workspaces/workspace-1/assets/documents/asset-doc-sync-1-plan.md';
+            const imagePath = 'workspaces/workspace-1/assets/images/asset-image-sync-1-proof.png';
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/push', routes);
+            const req = createMockReq('POST', '/api/taskforce/sync/workspace/push', {
+                workspaceId: 'workspace-1',
+                changes: [
+                    {
+                        op: 'document-upsert',
+                        path: markdownPath,
+                        updatedAt: '2026-03-18T23:20:00.000Z',
+                        content: '# Plan',
+                        assetId: 'asset-doc-sync-1',
+                        documentId: 'doc-sync-1',
+                        taskId: 'task-sync-1',
+                        originalFilename: 'plan.md',
+                        linkRole: 'attachment'
+                    },
+                    {
+                        op: 'asset-upsert',
+                        path: imagePath,
+                        updatedAt: '2026-03-18T23:20:01.000Z',
+                        contentBase64: Buffer.from('png-bytes').toString('base64'),
+                        assetId: 'asset-image-sync-1',
+                        kind: 'image',
+                        mimeType: 'image/png',
+                        taskId: 'task-sync-1',
+                        originalFilename: 'proof.png',
+                        linkRole: 'image'
+                    }
+                ]
+            }, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+            const docAsset = store.getByStorageKey(markdownPath, 'workspace-1');
+            const imageAsset = store.getByStorageKey(imagePath, 'workspace-1');
+            expect(docAsset).toEqual(expect.objectContaining({
+                assetId: 'asset-doc-sync-1',
+                storageProvider: 'r2',
+                storageKey: markdownPath
+            }));
+            expect(imageAsset).toEqual(expect.objectContaining({
+                assetId: 'asset-image-sync-1',
+                storageProvider: 'r2',
+                storageKey: imagePath
+            }));
+            expect(store.listLinksForTask('task-sync-1', 'workspace-1')).toEqual(expect.arrayContaining([
+                expect.objectContaining({ assetId: 'asset-doc-sync-1', role: 'attachment', deletedAt: null }),
+                expect.objectContaining({ assetId: 'asset-image-sync-1', role: 'image', deletedAt: null })
+            ]));
+            vi.unstubAllGlobals();
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+        });
+        it('POST /api/taskforce/sync/workspace/push should audit unauthorized access', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
                 enabled: true,
@@ -9417,6 +10146,127 @@ describe('Server Routes', () => {
             expect(res.setHeader).toHaveBeenCalledWith('Set-Cookie', expect.stringContaining('taskforce_session='));
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
+        it('POST /api/taskforce/session/workspace should allow a read-only user to switch to another active workspace', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            const cookie = createSessionTokenCookie('session-read-only', authConfig, {
+                role: 'read-only',
+                workspaceId: 'workspace-shared',
+                userId: 'user-1'
+            });
+            core.listUserWorkspaces.mockReturnValue([
+                {
+                    id: 'workspace-shared',
+                    slug: 'workspace-shared',
+                    name: 'Shared Workspace',
+                    description: null,
+                    role: 'read-only',
+                    status: 'active',
+                    betaAccess: true
+                },
+                {
+                    id: 'workspace-home',
+                    slug: 'workspace-home',
+                    name: 'Home Workspace',
+                    description: null,
+                    role: 'owner',
+                    status: 'active',
+                    betaAccess: true
+                }
+            ]);
+            core.resolveUserAccess.mockReturnValue({
+                userId: 'user-1',
+                workspaceId: 'workspace-home',
+                role: 'owner',
+                permissionMode: 'read-write',
+                disabled: false,
+                betaAccess: true
+            });
+            const match = matchRoute('POST', '/api/taskforce/session/workspace', routes);
+            const req = createMockReq('POST', '/api/taskforce/session/workspace', {
+                workspaceId: 'workspace-home'
+            }, {
+                cookie
+            });
+            const res = createMockRes();
+            res.setHeader = vi.fn();
+            await match?.handler(req, res, {});
+            expect(core.resolveUserAccess).toHaveBeenCalledWith('user-1', 'workspace-home', 'read-only');
+            expect(res.setHeader).toHaveBeenCalledWith('Set-Cookie', expect.stringContaining('taskforce_session='));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(String(res.end.mock.calls[0]?.[0] || '{}'));
+            expect(payload).toMatchObject({ success: true, workspaceId: 'workspace-home', role: 'owner' });
+        });
+        it('POST /api/taskforce/session/workspace should allow switching into an active read-only workspace', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            const cookie = createSessionTokenCookie('session-member', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-home',
+                userId: 'user-1'
+            });
+            core.listUserWorkspaces.mockReturnValue([
+                {
+                    id: 'workspace-home',
+                    slug: 'workspace-home',
+                    name: 'Home Workspace',
+                    description: null,
+                    role: 'owner',
+                    status: 'active',
+                    betaAccess: true
+                },
+                {
+                    id: 'workspace-shared',
+                    slug: 'workspace-shared',
+                    name: 'Shared Workspace',
+                    description: null,
+                    role: 'read-only',
+                    status: 'active',
+                    betaAccess: true
+                }
+            ]);
+            core.resolveUserAccess.mockReturnValue({
+                userId: 'user-1',
+                workspaceId: 'workspace-shared',
+                role: 'read-only',
+                permissionMode: 'read-only',
+                disabled: false,
+                betaAccess: true
+            });
+            const match = matchRoute('POST', '/api/taskforce/session/workspace', routes);
+            const req = createMockReq('POST', '/api/taskforce/session/workspace', {
+                workspaceId: 'workspace-shared'
+            }, {
+                cookie
+            });
+            const res = createMockRes();
+            res.setHeader = vi.fn();
+            await match?.handler(req, res, {});
+            expect(res.setHeader).toHaveBeenCalledWith('Set-Cookie', expect.stringContaining('taskforce_session='));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(String(res.end.mock.calls[0]?.[0] || '{}'));
+            expect(payload).toMatchObject({ success: true, workspaceId: 'workspace-shared', role: 'read-only' });
+        });
         it('POST /api/taskforce/session/workspace should be disabled in local runtime', async () => {
             const authConfig = {
                 runtimeMode: 'local',
@@ -9513,6 +10363,7 @@ describe('Server Routes', () => {
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.authenticated).toBe(true);
             expect(payload.betaAccess).toBe(false);
+            expect(res.setHeader).toHaveBeenCalledWith('Server-Timing', expect.stringContaining('auth-session'));
             expect(core.getUserBetaAccess).toHaveBeenCalledWith('u-no-workspace');
         });
         it('GET /api/taskforce/auth/session should expose avatarUrl from the resolved profile', async () => {
@@ -9723,6 +10574,74 @@ describe('Server Routes', () => {
                 mimeType: 'image/png'
             }));
         });
+        it('POST /api/taskforce/auth/profile/avatar/upload should store the avatar body through object storage', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            const fetchMock = vi.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: 'OK',
+                text: async () => ''
+            });
+            vi.stubGlobal('fetch', fetchMock);
+            const routesWithStorage = createRoutes(core, {
+                authConfig,
+                objectStorage: {
+                    provider: 'r2',
+                    r2: {
+                        accountId: 'acct-1',
+                        bucket: 'taskforce-docs',
+                        endpoint: 'https://example.r2.cloudflarestorage.com',
+                        accessKeyId: 'access-key-1',
+                        secretAccessKey: 'secret-key-1',
+                        keyPrefix: 'taskforce',
+                        signedUploadTtlSeconds: 600,
+                        signedDownloadTtlSeconds: 300
+                    }
+                }
+            });
+            core.getUserAvatarUploadDraft.mockReturnValueOnce({
+                draftId: 'avatar-draft-1',
+                userId: 'u1',
+                storageKey: 'users/u1/profile/avatar/avatar-draft-1-headshot.png',
+                mimeType: 'image/png',
+                finalizedAt: null,
+                discardedAt: null
+            });
+            const cookie = createSessionTokenCookie('session-avatar-upload', authConfig, {
+                userId: 'u1',
+                role: 'member',
+                workspaceId: 'workspace-1'
+            });
+            const match = matchRoute('POST', '/api/taskforce/auth/profile/avatar/upload', routesWithStorage);
+            const req = createMockReq('POST', '/api/taskforce/auth/profile/avatar/upload', Buffer.from([1, 2, 3, 4]), {
+                cookie,
+                'content-type': 'image/png',
+                'x-taskforce-avatar-draft-id': 'avatar-draft-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.success).toBe(true);
+            expect(payload.draftId).toBe('avatar-draft-1');
+            const r2Call = fetchMock.mock.calls[0];
+            expect(String(r2Call?.[0])).toContain('https://example.r2.cloudflarestorage.com/taskforce-docs/taskforce/users/u1/profile/avatar/avatar-draft-1-headshot.png');
+            expect(r2Call?.[1]).toEqual(expect.objectContaining({
+                method: 'PUT',
+                body: expect.any(Uint8Array)
+            }));
+            expect((r2Call?.[1]?.headers)['content-type']).toBe('image/png');
+            vi.unstubAllGlobals();
+        });
         it('POST /api/taskforce/auth/profile/avatar/finalize should validate and finalize the uploaded draft', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -9847,6 +10766,56 @@ describe('Server Routes', () => {
                 allowed: true
             });
         });
+        it('GET /api/taskforce/account/team-management-access should resolve against the authenticated session user and workspace', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValueOnce([
+                { id: 'workspace-auth-existing-home', slug: 'home', name: 'Home', description: null, role: 'owner', status: 'active', betaAccess: true },
+                { id: 'workspace-invited', slug: 'invited', name: 'Invited', description: null, role: 'member', status: 'active', betaAccess: true }
+            ]);
+            core.resolveUserAccess.mockImplementation((userId, workspaceId, role) => ({
+                userId,
+                workspaceId,
+                role: userId === 'joined-member' && workspaceId === 'workspace-invited' ? 'member' : role,
+                disabled: false,
+                betaAccess: true
+            }));
+            const cookie = createSessionTokenCookie('session-joined-member', authConfig, {
+                userId: 'joined-member',
+                role: 'member',
+                workspaceId: 'workspace-invited'
+            });
+            const match = matchRoute('GET', '/api/taskforce/account/team-management-access', routes);
+            const req = createMockReq('GET', '/api/taskforce/account/team-management-access', undefined, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-user-id': 'workspace-auth-existing-home-owner',
+                'x-taskforce-workspace-id': 'workspace-auth-existing-home',
+                'x-taskforce-role': 'owner'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.resolveUserAccess).toHaveBeenCalledWith('joined-member', 'workspace-invited', 'member');
+            expect(core.getAccountEntitlementsPayload).toHaveBeenCalledWith({ userId: 'joined-member', workspaceId: 'workspace-invited' });
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload).toMatchObject({
+                workspaceId: 'workspace-invited',
+                role: 'member',
+                canManageWorkspace: false,
+                teamPlanMode: 'team',
+                allowed: false
+            });
+        });
         it('GET /api/taskforce/account/team-management-access should fall back to the hinted workspace role when local access cannot resolve the cloud user id', async () => {
             core.resolveUserAccess.mockReturnValueOnce(null);
             const match = matchRoute('GET', '/api/taskforce/account/team-management-access', routes);
@@ -9923,6 +10892,40 @@ describe('Server Routes', () => {
                 planSelectionRequired: false
             });
         });
+        it('GET /api/taskforce/account/ai-profile-seat-usage should return cloud-authoritative ai seat usage', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.countAiProfileUsage.mockReturnValueOnce({ used: 0, limit: 20, remaining: 20 });
+            const match = matchRoute('GET', '/api/taskforce/account/ai-profile-seat-usage', routes);
+            const cookie = createSessionTokenCookie('session-ai-seat-usage', authConfig, {
+                userId: 'u1',
+                role: 'owner',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('GET', '/api/taskforce/account/ai-profile-seat-usage?workspaceId=workspace-1', undefined, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-user-id': 'u1',
+                'x-taskforce-role': 'owner',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.countAiProfileUsage).toHaveBeenCalledWith('workspace-1');
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.aiProfileSeatUsage).toEqual({ used: 0, limit: 20, remaining: 20 });
+        });
         it('GET /api/taskforce/account/access-status should return pending plan-selection gate', async () => {
             core.getAccountAccessStatus.mockReturnValueOnce({
                 gate: 'plan_selection_required',
@@ -9995,6 +10998,78 @@ describe('Server Routes', () => {
                 error.code = 'ENTITLEMENT_NOT_FOUND';
                 throw error;
             });
+            core.countAiProfileUsage.mockReturnValueOnce({ used: 0, limit: 20, remaining: 20 });
+            const match = matchRoute('GET', '/api/taskforce/account/profile-summary', routes);
+            const req = createMockReq('GET', '/api/taskforce/account/profile-summary?workspaceId=workspace-1', undefined, {
+                'x-taskforce-user-id': 'u1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload).toMatchObject({
+                planId: 'pro',
+                planVersionId: 'pro-v1',
+                entitlementState: 'checkout_pending',
+                gate: 'checkout_pending',
+                message: 'Complete checkout to continue.',
+                billingConflictCode: null,
+                planSelectionRequired: false,
+                workspaceId: 'workspace-1',
+                workspaceRole: 'owner',
+                canManageWorkspace: true,
+                teamPlanMode: 'personal',
+                teamManagementAllowed: false,
+                aiProfileSeatUsage: {
+                    used: 0,
+                    limit: 20,
+                    remaining: 20
+                }
+            });
+        });
+        it('GET /api/taskforce/account/profile-summary should not leak stale billing mirror plan identity when entitlement is missing', async () => {
+            core.resolveUserAccess.mockReturnValueOnce({
+                userId: 'u1',
+                workspaceId: 'workspace-1',
+                role: 'member',
+                disabled: false,
+                betaAccess: true
+            });
+            core.getAccountAccessStatus.mockReturnValueOnce({
+                gate: 'missing_entitlement',
+                hasEntitlement: false,
+                canAccessApp: false,
+                canAccessPlans: true,
+                planSelectionRequired: false,
+                message: 'No entitlement is linked to this account.',
+                entitlement: null
+            });
+            core.countAiProfileUsage.mockReturnValueOnce({ used: 0, limit: 20, remaining: 20 });
+            const baseDb = core.getDatabaseAdapter();
+            core.getDatabaseAdapter = vi.fn().mockReturnValue({
+                ...baseDb,
+                prepare: vi.fn((sql) => {
+                    if (sql.includes('FROM user_billing')) {
+                        return {
+                            get: () => ({
+                                stripe_status: 'active',
+                                stripe_customer_id: 'cus_stale',
+                                stripe_subscription_id: 'sub_stale',
+                                stripe_price_id: 'price_stale',
+                                billing_interval: 'month',
+                                entitlement_state: 'active',
+                                tier: 'team-5'
+                            })
+                        };
+                    }
+                    if (sql.includes('FROM plan_catalog')) {
+                        return {
+                            get: () => ({ display_name: 'Team 5' })
+                        };
+                    }
+                    return baseDb.prepare(sql);
+                })
+            });
             const match = matchRoute('GET', '/api/taskforce/account/profile-summary', routes);
             const req = createMockReq('GET', '/api/taskforce/account/profile-summary?workspaceId=workspace-1', undefined, {
                 'x-taskforce-user-id': 'u1'
@@ -10004,18 +11079,15 @@ describe('Server Routes', () => {
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload).toMatchObject({
-                planId: 'pro',
-                planVersionId: 'pro-v1',
-                entitlementState: 'checkout_pending',
-                gate: 'checkout_pending',
-                message: 'Complete checkout to continue.',
-                billingConflictCode: null,
+                planId: null,
+                planVersionId: null,
+                entitlementState: null,
+                gate: 'missing_entitlement',
+                message: 'No entitlement is linked to this account.',
                 planSelectionRequired: false,
-                workspaceId: 'workspace-1',
-                workspaceRole: 'owner',
-                canManageWorkspace: true,
-                teamPlanMode: 'personal',
-                teamManagementAllowed: false
+                stripeStatus: 'active',
+                stripeCustomerId: 'cus_stale',
+                stripeSubscriptionId: 'sub_stale'
             });
         });
         it('GET /api/taskforce/account/entitlements should surface checkout-pending gate when billing is not complete', async () => {
@@ -10087,6 +11159,20 @@ describe('Server Routes', () => {
             expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"code":"PLAN_SELECTION_REQUIRED"'));
             expect(core.listTasks).not.toHaveBeenCalled();
         });
+        it('GET /api/taskforce/tasks should require authenticated cloud users', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listTasks.mockReturnValue({ tasks: [] });
+            const match = matchRoute('GET', '/api/taskforce/tasks', routes);
+            const req = createMockReq('GET', '/api/taskforce/tasks', undefined, {
+                'x-taskforce-runtime-mode': 'cloud'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(401, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"Authentication required."'));
+            expect(core.listTasks).not.toHaveBeenCalled();
+        });
         it('GET /api/taskforce/tasks should block authenticated users with missing entitlements', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -10194,17 +11280,31 @@ describe('Server Routes', () => {
             try {
                 core.getTenantId = vi.fn().mockReturnValue('default');
                 core.getDatabaseAdapter = vi.fn().mockReturnValue({
-                    prepare: vi.fn().mockReturnValue({
-                        all: vi.fn().mockReturnValue([
-                            {
-                                plan_version_id: 'free-v1',
-                                billing_interval: 'month',
-                                stripe_price_id: 'free:free-v1:month',
-                                pricing_type: 'free',
-                                unit_amount: 0,
-                                currency: null
-                            }
-                        ])
+                    prepare: vi.fn().mockImplementation((sql) => {
+                        if (sql.includes('FROM billing_price_mappings')) {
+                            return {
+                                get: vi.fn().mockReturnValue({
+                                    count: 1,
+                                    max_updated_at: '2026-01-01T00:00:00.000Z'
+                                }),
+                                all: vi.fn().mockReturnValue([
+                                    {
+                                        plan_version_id: 'free-v1',
+                                        billing_interval: 'month',
+                                        stripe_price_id: 'free:free-v1:month',
+                                        pricing_type: 'free',
+                                        unit_amount: 0,
+                                        currency: null
+                                    }
+                                ])
+                            };
+                        }
+                        return {
+                            get: vi.fn().mockReturnValue({
+                                count: 0,
+                                max_updated_at: null
+                            })
+                        };
                     })
                 });
                 core.listPlanCatalog.mockReturnValueOnce([
@@ -10224,6 +11324,7 @@ describe('Server Routes', () => {
                         }
                     }
                 ]);
+                core.listPlanFeatureCatalog = vi.fn().mockReturnValue([]);
                 routes = createRoutes(core);
                 const match = matchRoute('GET', '/api/taskforce/public/pricing', routes);
                 const req = createMockReq('GET', '/api/taskforce/public/pricing', undefined, {
@@ -10235,7 +11336,15 @@ describe('Server Routes', () => {
                 const payload = JSON.parse(String(res.end.mock.calls[0][0]));
                 expect(payload.plans).toHaveLength(1);
                 expect(payload.plans[0].features).toEqual([
-                    { featureKey: 'ai.assistance', access: 'enabled', config: {} }
+                    {
+                        featureKey: 'ai.assistance',
+                        access: 'enabled',
+                        config: {},
+                        label: null,
+                        description: null,
+                        publicLabel: null,
+                        publicDescription: null
+                    }
                 ]);
             }
             finally {
@@ -10267,6 +11376,7 @@ describe('Server Routes', () => {
             expect(core.upsertPlanCatalog).toHaveBeenCalledWith({
                 planId: 'enterprise',
                 displayName: 'Enterprise',
+                description: undefined,
                 status: 'active',
                 initialTrialDays: 0,
                 initialMode: undefined,
@@ -10286,6 +11396,42 @@ describe('Server Routes', () => {
             expect(core.listPlanCatalog).toHaveBeenCalled();
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
+        it('GET /api/platform/onboarding-plan-options should return onboarding plan options for system admin', async () => {
+            core.listOnboardingPlanOptions = vi.fn().mockReturnValue([
+                {
+                    planId: 'free',
+                    planDisplayName: 'Free',
+                    defaultPlanVersionId: 'free-v1',
+                    defaultVersionNumber: 1,
+                    planStatus: 'active',
+                    supportsAutoGrantFree: true,
+                    supportsAutoStartTrial: false
+                }
+            ]);
+            const match = matchRoute('GET', '/api/platform/onboarding-plan-options', routes);
+            const req = createMockReq('GET', '/api/platform/onboarding-plan-options', undefined, {
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-system-role': 'system_admin'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.listOnboardingPlanOptions).toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(JSON.parse(res.end.mock.calls[0]?.[0] || '{}')).toEqual({
+                success: true,
+                options: [
+                    {
+                        planId: 'free',
+                        planDisplayName: 'Free',
+                        defaultPlanVersionId: 'free-v1',
+                        defaultVersionNumber: 1,
+                        planStatus: 'active',
+                        supportsAutoGrantFree: true,
+                        supportsAutoStartTrial: false
+                    }
+                ]
+            });
+        });
         it('GET /api/platform/plans/:planId/versions should list versions', async () => {
             const match = matchRoute('GET', '/api/platform/plans/collab/versions', routes);
             const req = createMockReq('GET', '/api/platform/plans/collab/versions', undefined, {
@@ -10344,6 +11490,37 @@ describe('Server Routes', () => {
             expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"featureKey":"collaboration.team_management"'));
             expect(res.end).not.toHaveBeenCalledWith(expect.stringContaining('"featureKey":"collaboration.invites"'));
         });
+        it('PATCH /api/platform/features/:featureKey should update public marketing copy', async () => {
+            core.updatePlanFeatureCatalogMarketingCopy = vi.fn().mockReturnValue({
+                featureKey: 'collaboration.ai_profiles',
+                label: 'AI Profiles',
+                description: 'Allow registered AI collaborator profiles with an optional per-workspace limit.',
+                publicLabel: 'AI teammates',
+                publicDescription: 'Add reusable AI teammates to your workspace.',
+                publicDisplayOrder: 20,
+                allowedAccessModes: ['enabled', 'limited', 'disabled'],
+                configTemplate: { maxAiProfiles: 1 }
+            });
+            const match = matchRoute('PATCH', '/api/platform/features/collaboration.ai_profiles', routes);
+            const req = createMockReq('PATCH', '/api/platform/features/collaboration.ai_profiles', {
+                publicLabel: 'AI teammates',
+                publicDescription: 'Add reusable AI teammates to your workspace.',
+                publicDisplayOrder: 20
+            }, {
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-system-role': 'system_admin'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { featureKey: 'collaboration.ai_profiles' });
+            expect(core.updatePlanFeatureCatalogMarketingCopy).toHaveBeenCalledWith({
+                featureKey: 'collaboration.ai_profiles',
+                publicLabel: 'AI teammates',
+                publicDescription: 'Add reusable AI teammates to your workspace.',
+                publicDisplayOrder: 20
+            });
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"publicLabel":"AI teammates"'));
+        });
         it('PATCH /api/platform/plans/:planId/versions/:versionId/features should return normalized dependency state', async () => {
             core.updatePlanVersionFeatures.mockReturnValueOnce({
                 planVersionId: 'collab-v1',
@@ -10473,13 +11650,20 @@ describe('Server Routes', () => {
                     updatedAt: '2026-02-01T00:00:00.000Z'
                 }
             ]);
+            core.countSystemUsers.mockReturnValueOnce(1);
             const match = matchRoute('GET', '/api/taskforce/admin/system-users', routes);
-            const req = createMockReq('GET', '/api/taskforce/admin/system-users', undefined, { 'x-taskforce-system-role': 'system_admin' });
+            const req = createMockReq('GET', '/api/taskforce/admin/system-users?q=u1&sort=oldest&limit=25&offset=50', undefined, { 'x-taskforce-system-role': 'system_admin' });
             const res = createMockRes();
             await match?.handler(req, res, {});
-            expect(core.listSystemUsers).toHaveBeenCalled();
+            expect(core.countSystemUsers).toHaveBeenCalledWith({ query: 'u1' });
+            expect(core.listSystemUsers).toHaveBeenCalledWith({ query: 'u1', sort: 'oldest', limit: 25, offset: 50 });
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
-            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"users"'));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.users).toHaveLength(1);
+            expect(payload.total).toBe(1);
+            expect(payload.limit).toBe(25);
+            expect(payload.offset).toBe(50);
+            expect(payload.hasMore).toBe(false);
         });
         it('GET /api/taskforce/admin/system-users should allow authenticated system admin without role header', async () => {
             const authConfig = {
@@ -10505,7 +11689,8 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.getSystemRole).toHaveBeenCalledWith('admin-user');
-            expect(core.listSystemUsers).toHaveBeenCalled();
+            expect(core.countSystemUsers).toHaveBeenCalledWith({ query: '' });
+            expect(core.listSystemUsers).toHaveBeenCalledWith({ query: '', sort: 'newest', limit: 50, offset: 0 });
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
         it('GET /api/taskforce/admin/audit-logs should return events for admins', async () => {
@@ -10767,6 +11952,266 @@ describe('Server Routes', () => {
             expect(matchRoute('POST', '/api/taskforce/admin/users/invite', routes)).not.toBeNull();
             expect(matchRoute('PATCH', '/api/taskforce/admin/users/u1/role', routes)).not.toBeNull();
             expect(matchRoute('GET', '/api/taskforce/admin/workspace-audit-logs', routes)).not.toBeNull();
+            expect(matchRoute('POST', '/api/taskforce/workspace/ai-profiles/avatar', routes)).not.toBeNull();
+        });
+        it('POST /api/taskforce/admin/users/invite should authorize against the target workspace', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([
+                { id: 'workspace-home', slug: 'home', name: 'Home', role: 'owner', status: 'active', betaAccess: true },
+                { id: 'workspace-shared', slug: 'shared', name: 'Shared', role: 'member', status: 'active', betaAccess: true }
+            ]);
+            core.listWorkspaceUsers.mockImplementation((workspaceId) => {
+                if (workspaceId === 'workspace-home') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'owner',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                if (workspaceId === 'workspace-shared') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'member',
+                            permissionMode: 'read-only',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                return [];
+            });
+            core.inviteWorkspaceUser.mockReturnValue({
+                userId: 'invited-user',
+                email: 'invited@example.com',
+                role: 'member',
+                status: 'invited',
+                disabled: false
+            });
+            const cookie = createSessionTokenCookie('session-target-invite-deny', authConfig, {
+                userId: 'actor-user',
+                role: 'owner',
+                workspaceId: 'workspace-home'
+            });
+            const match = matchRoute('POST', '/api/taskforce/admin/users/invite', routes);
+            const req = createMockReq('POST', '/api/taskforce/admin/users/invite', {
+                workspaceId: 'workspace-shared',
+                email: 'invited@example.com',
+                role: 'member'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'owner',
+                'x-taskforce-user-id': 'actor-user',
+                'x-taskforce-workspace-id': 'workspace-home'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.inviteWorkspaceUser).not.toHaveBeenCalled();
+            expect(core.evaluateFeatureAccess).not.toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(403, expect.any(Object));
+        });
+        it('POST /api/taskforce/admin/users/invite should resolve feature access and inviter identity from the authenticated session user', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listWorkspaceUsers.mockImplementation((workspaceId) => {
+                if (workspaceId === 'workspace-shared') {
+                    return [{
+                            userId: 'joined-admin',
+                            email: 'joined-admin@example.com',
+                            displayName: 'Joined Admin',
+                            role: 'admin',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                return [];
+            });
+            core.evaluateFeatureAccess.mockImplementation(({ userId }) => ({
+                allowed: userId === 'joined-admin',
+                reasonCode: userId === 'joined-admin' ? undefined : 'ACCOUNT_ENTITLEMENT_REQUIRED'
+            }));
+            core.inviteWorkspaceUser.mockReturnValue({
+                userId: 'invited-user',
+                email: 'invited@example.com',
+                role: 'member',
+                status: 'invited',
+                disabled: false
+            });
+            core.requestInviteAcceptance.mockReturnValue({ token: 'invite-token-1' });
+            core.getWorkspaceProfile.mockReturnValue({
+                id: 'workspace-shared',
+                name: 'Shared Workspace'
+            });
+            core.resolveUserIdentity.mockReturnValue({
+                userId: 'joined-admin',
+                email: 'joined-admin@example.com',
+                displayName: 'Joined Admin'
+            });
+            const cookie = createSessionTokenCookie('session-target-invite-identity', authConfig, {
+                userId: 'joined-admin',
+                role: 'admin',
+                workspaceId: 'workspace-shared'
+            });
+            const match = matchRoute('POST', '/api/taskforce/admin/users/invite', routes);
+            const req = createMockReq('POST', '/api/taskforce/admin/users/invite', {
+                workspaceId: 'workspace-shared',
+                email: 'invited@example.com',
+                role: 'member'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'owner',
+                'x-taskforce-user-id': 'workspace-auth-existing-home-owner',
+                'x-taskforce-workspace-id': 'workspace-auth-existing-home'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.evaluateFeatureAccess).toHaveBeenCalledWith(expect.objectContaining({
+                userId: 'joined-admin',
+                workspaceId: 'workspace-shared',
+                featureKey: 'collaboration.invites'
+            }));
+            expect(core.resolveUserIdentity).toHaveBeenCalledWith('joined-admin');
+            expect(core.inviteWorkspaceUser).toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        });
+        it('PATCH /api/taskforce/admin/users/:id/role should reject active-workspace admins who are only target-workspace members', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([
+                { id: 'workspace-home', slug: 'home', name: 'Home', role: 'owner', status: 'active', betaAccess: true },
+                { id: 'workspace-shared', slug: 'shared', name: 'Shared', role: 'member', status: 'active', betaAccess: true }
+            ]);
+            core.listWorkspaceUsers.mockImplementation((workspaceId) => {
+                if (workspaceId === 'workspace-home') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'owner',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                if (workspaceId === 'workspace-shared') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'member',
+                            permissionMode: 'read-only',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                return [];
+            });
+            core.updateWorkspaceUserRole.mockReturnValue(true);
+            const cookie = createSessionTokenCookie('session-target-role-deny', authConfig, {
+                userId: 'actor-user',
+                role: 'owner',
+                workspaceId: 'workspace-home'
+            });
+            const match = matchRoute('PATCH', '/api/taskforce/admin/users/target-user/role', routes);
+            const req = createMockReq('PATCH', '/api/taskforce/admin/users/target-user/role', {
+                workspaceId: 'workspace-shared',
+                role: 'admin'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'owner',
+                'x-taskforce-user-id': 'actor-user',
+                'x-taskforce-workspace-id': 'workspace-home'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { id: 'target-user' });
+            expect(core.updateWorkspaceUserRole).not.toHaveBeenCalled();
+            expect(core.evaluateFeatureAccess).not.toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(403, expect.any(Object));
+        });
+        it('PATCH /api/taskforce/admin/users/:id/role should allow target-workspace admins with a different active workspace', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([
+                { id: 'workspace-home', slug: 'home', name: 'Home', role: 'member', status: 'active', betaAccess: true },
+                { id: 'workspace-shared', slug: 'shared', name: 'Shared', role: 'admin', status: 'active', betaAccess: true }
+            ]);
+            core.listWorkspaceUsers.mockImplementation((workspaceId) => {
+                if (workspaceId === 'workspace-home') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'member',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                if (workspaceId === 'workspace-shared') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'admin',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                return [];
+            });
+            core.updateWorkspaceUserRole.mockReturnValue(true);
+            const cookie = createSessionTokenCookie('session-target-role-allow', authConfig, {
+                userId: 'actor-user',
+                role: 'member',
+                workspaceId: 'workspace-home'
+            });
+            const match = matchRoute('PATCH', '/api/taskforce/admin/users/target-user/role', routes);
+            const req = createMockReq('PATCH', '/api/taskforce/admin/users/target-user/role', {
+                workspaceId: 'workspace-shared',
+                role: 'admin'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'member',
+                'x-taskforce-user-id': 'actor-user',
+                'x-taskforce-workspace-id': 'workspace-home'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { id: 'target-user' });
+            expect(core.evaluateFeatureAccess).toHaveBeenCalledWith({
+                userId: 'actor-user',
+                workspaceId: 'workspace-shared',
+                featureKey: 'collaboration.team_management'
+            });
+            expect(core.updateWorkspaceUserRole).toHaveBeenCalledWith('target-user', 'workspace-shared', 'admin');
+            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'update-workspace-user-role',
+                actorUserId: 'actor-user',
+                actorRole: 'admin',
+                workspaceId: 'workspace-shared',
+                details: expect.objectContaining({
+                    workspaceId: 'workspace-shared',
+                    targetUserId: 'target-user'
+                })
+            }));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
         it('GET /api/taskforce/workspace/assignee-options should reject unauthenticated cloud requests', async () => {
             const authConfig = {
@@ -10861,6 +12306,7 @@ describe('Server Routes', () => {
                     userId: 'member-1',
                     email: 'member1@example.com',
                     displayName: 'Member One',
+                    avatarUrl: '/api/taskforce/context/users%2Fmember-1%2Fprofile%2Favatar%2Fheadshot.webp',
                     role: 'member',
                     permissionMode: 'read-write',
                     betaAccess: true,
@@ -10882,11 +12328,14 @@ describe('Server Routes', () => {
                     provider: 'OpenAI',
                     model: 'gpt-5.4',
                     surfaceType: 'coding_tool',
+                    seatScope: null,
+                    archivedAt: null,
                     createdAt: '2026-03-01T00:00:00.000Z',
                     updatedAt: '2026-03-01T00:00:00.000Z',
                     lastActiveAt: null
                 }
             ]);
+            core.countAiProfileUsage.mockReturnValue({ used: 1, limit: 3, remaining: 2 });
             const match = matchRoute('GET', '/api/taskforce/workspace/assignee-options', routes);
             const cookie = createSessionTokenCookie('session-member-assignees', authConfig, {
                 userId: 'member-user',
@@ -10903,9 +12352,14 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.listWorkspaceUsers).toHaveBeenCalledWith('workspace-1');
-            expect(core.listAiProfiles).toHaveBeenCalledWith('workspace-1');
+            expect(core.listAiProfiles).toHaveBeenCalledWith('workspace-1', expect.objectContaining({
+                diagnostics: expect.any(Object)
+            }));
+            expect(core.countAiProfileUsage).toHaveBeenCalledWith('workspace-1');
+            expect(res.setHeader).toHaveBeenCalledWith('Server-Timing', expect.stringContaining('assignee-options'));
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.aiProfileSeatUsage).toEqual({ used: 1, limit: 3, remaining: 2 });
             expect(payload.assignees).toEqual([
                 {
                     value: 'member-1',
@@ -10916,6 +12370,7 @@ describe('Server Routes', () => {
                     userId: 'member-1',
                     email: 'member1@example.com',
                     displayName: 'Member One',
+                    avatarUrl: '/api/taskforce/context/users%2Fmember-1%2Fprofile%2Favatar%2Fheadshot.webp',
                     status: 'active',
                     disabled: false
                 },
@@ -10925,12 +12380,16 @@ describe('Server Routes', () => {
                     username: 'codex',
                     icon: 'Bot',
                     color: '#ef6c00',
+                    avatarUrl: null,
+                    avatarSourceUrl: null,
                     kind: 'agent',
                     description: 'Builds product code',
                     role: 'Implementer',
                     provider: 'OpenAI',
                     model: 'gpt-5.4',
                     surfaceType: 'coding_tool',
+                    seatScope: null,
+                    archivedAt: null,
                     createdAt: '2026-03-01T00:00:00.000Z',
                     updatedAt: '2026-03-01T00:00:00.000Z',
                     lastActiveAt: null
@@ -10970,6 +12429,7 @@ describe('Server Routes', () => {
                     lastActiveAt: null
                 }
             ]);
+            core.countAiProfileUsage.mockReturnValue({ used: 1, limit: 3, remaining: 2 });
             const match = matchRoute('GET', '/api/taskforce/workspace/assignee-options', routes);
             const cookie = createSessionTokenCookie('session-admin-assignees', authConfig, {
                 userId: 'admin-user',
@@ -10986,6 +12446,7 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.aiProfileSeatUsage).toEqual({ used: 1, limit: 3, remaining: 2 });
             expect(payload.assignees).toEqual([
                 expect.objectContaining({
                     value: 'ai-profile-1',
@@ -10993,6 +12454,198 @@ describe('Server Routes', () => {
                 })
             ]);
         });
+        it('POST /api/taskforce/workspace/ai-profiles/archive should archive active profiles for workspace admins', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.archiveAiProfile.mockReturnValue({
+                id: 'ai-profile-1',
+                workspaceId: 'workspace-1',
+                profileToken: 'tfp_codex_sync',
+                name: 'Codex',
+                username: 'codex',
+                icon: 'Bot',
+                color: '#ef6c00',
+                description: 'Builds product code',
+                role: 'Implementer',
+                provider: 'OpenAI',
+                model: 'gpt-5.4',
+                surfaceType: 'coding_tool',
+                archivedAt: '2026-04-19T17:00:00.000Z',
+                archivedBy: 'admin-user',
+                archivedReason: 'manual_archive',
+                mergedIntoProfileId: null,
+                createdAt: '2026-03-01T00:00:00.000Z',
+                updatedAt: '2026-04-19T17:00:00.000Z',
+                lastActiveAt: null
+            });
+            const match = matchRoute('POST', '/api/taskforce/workspace/ai-profiles/archive', routes);
+            const cookie = createSessionTokenCookie('session-admin-archive-ai-profile', authConfig, {
+                userId: 'admin-user',
+                role: 'admin',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('POST', '/api/taskforce/workspace/ai-profiles/archive', {
+                profileId: 'ai-profile-1',
+                reason: 'manual_archive'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'admin',
+                'x-taskforce-user-id': 'admin-user',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.archiveAiProfile).toHaveBeenCalledWith({
+                workspaceId: 'workspace-1',
+                profileId: 'ai-profile-1',
+                archivedBy: 'admin-user',
+                reason: 'manual_archive'
+            });
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.profile).toEqual(expect.objectContaining({
+                id: 'ai-profile-1',
+                archivedReason: 'manual_archive'
+            }));
+        });
+        it('POST /api/taskforce/workspace/ai-profiles/archive should honor actual owner membership even when the request role is stale', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([
+                {
+                    id: 'workspace-1',
+                    slug: 'workspace-1',
+                    name: 'Workspace 1',
+                    description: null,
+                    role: 'owner',
+                    status: 'active',
+                    betaAccess: true
+                }
+            ]);
+            core.listWorkspaceUsers.mockReturnValue([
+                {
+                    userId: 'owner-user',
+                    email: 'owner@example.com',
+                    displayName: 'Owner User',
+                    role: 'owner',
+                    permissionMode: 'read-write',
+                    betaAccess: true,
+                    status: 'active',
+                    disabled: false
+                }
+            ]);
+            core.archiveAiProfile.mockReturnValue({
+                id: 'ai-profile-1',
+                workspaceId: 'workspace-1',
+                profileToken: 'tfp_codex_sync',
+                name: 'Codex',
+                username: 'codex',
+                icon: 'Bot',
+                color: '#ef6c00',
+                description: 'Builds product code',
+                role: 'Implementer',
+                provider: 'OpenAI',
+                model: 'gpt-5.4',
+                surfaceType: 'coding_tool',
+                archivedAt: '2026-04-19T17:00:00.000Z',
+                archivedBy: 'owner-user',
+                archivedReason: 'manual_archive',
+                mergedIntoProfileId: null,
+                createdAt: '2026-03-01T00:00:00.000Z',
+                updatedAt: '2026-04-19T17:00:00.000Z',
+                lastActiveAt: null
+            });
+            const match = matchRoute('POST', '/api/taskforce/workspace/ai-profiles/archive', routes);
+            const cookie = createSessionTokenCookie('session-owner-archive', authConfig, {
+                userId: 'owner-user',
+                role: 'member',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('POST', '/api/taskforce/workspace/ai-profiles/archive', {
+                profileId: 'ai-profile-1'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'member',
+                'x-taskforce-user-id': 'owner-user',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.archiveAiProfile).toHaveBeenCalledWith(expect.objectContaining({
+                workspaceId: 'workspace-1',
+                profileId: 'ai-profile-1',
+                archivedBy: 'owner-user'
+            }));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        });
+        it('POST /api/taskforce/workspace/ai-profiles/archive should surface open-task conflicts', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            const error = new Error('This AI profile still owns open tasks. Reassign or close them before removing it from the roster.');
+            error.statusCode = 409;
+            error.details = { workspaceId: 'workspace-1', profileId: 'ai-profile-1', openTaskCount: 2 };
+            core.archiveAiProfile.mockImplementation(() => {
+                throw error;
+            });
+            const match = matchRoute('POST', '/api/taskforce/workspace/ai-profiles/archive', routes);
+            const cookie = createSessionTokenCookie('session-admin-archive-ai-profile-conflict', authConfig, {
+                userId: 'admin-user',
+                role: 'admin',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('POST', '/api/taskforce/workspace/ai-profiles/archive', {
+                profileId: 'ai-profile-1',
+                reason: 'manual_archive'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'admin',
+                'x-taskforce-user-id': 'admin-user',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(409, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.error).toContain('This AI profile still owns open tasks');
+            expect(payload.details).toEqual({
+                workspaceId: 'workspace-1',
+                profileId: 'ai-profile-1',
+                openTaskCount: 2
+            });
+        });
         it('GET /api/taskforce/admin/workspace-audit-logs should return events for workspace admins', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -11090,13 +12743,13 @@ describe('Server Routes', () => {
                 billing: {
                     onboardingPolicy: {
                         mode: 'auto_grant_free',
-                        planVersionId: 'starter-v1'
+                        planId: 'starter'
                     }
                 }
             });
             core.getOnboardingPolicy.mockReturnValue({
                 mode: 'auto_grant_free',
-                planVersionId: 'starter-v1'
+                planId: 'starter'
             });
             const match = matchRoute('GET', '/api/taskforce/admin/system-settings', routes);
             const req = createMockReq('GET', '/api/taskforce/admin/system-settings', undefined, { 'x-taskforce-role': 'admin' });
@@ -11104,9 +12757,9 @@ describe('Server Routes', () => {
             await match?.handler(req, res, {});
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.status.onboardingPolicyMode).toBe('auto_grant_free');
-            expect(payload.status.onboardingPlanVersionId).toBe('starter-v1');
+            expect(payload.status.onboardingPlanId).toBe('starter');
             expect(payload.settings.onboardingPolicyMode).toBe('auto_grant_free');
-            expect(payload.settings.onboardingPlanVersionId).toBe('starter-v1');
+            expect(payload.settings.onboardingPlanId).toBe('starter');
         });
         it('POST /api/taskforce/admin/system-settings should persist onboarding policy fields', async () => {
             const match = matchRoute('POST', '/api/taskforce/admin/system-settings', routes);
@@ -11118,13 +12771,13 @@ describe('Server Routes', () => {
                 authRateLimitMaxRequests: 10,
                 authRateLimitWindowMs: 900000,
                 onboardingPolicyMode: 'auto_grant_free',
-                onboardingPlanVersionId: 'starter-v1'
+                onboardingPlanId: 'starter'
             }, { 'x-taskforce-role': 'admin' });
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.validateOnboardingPolicy).toHaveBeenCalledWith({
                 mode: 'auto_grant_free',
-                planVersionId: 'starter-v1'
+                planId: 'starter'
             });
             expect(core.updateGlobalSettings).toHaveBeenCalledWith({
                 auth: {
@@ -11138,7 +12791,7 @@ describe('Server Routes', () => {
                 billing: {
                     onboardingPolicy: {
                         mode: 'auto_grant_free',
-                        planVersionId: 'starter-v1'
+                        planId: 'starter'
                     }
                 }
             });
@@ -11146,7 +12799,7 @@ describe('Server Routes', () => {
         it('POST /api/taskforce/admin/system-settings should preserve onboarding policy when onboarding fields are omitted', async () => {
             core.getOnboardingPolicy.mockReturnValue({
                 mode: 'auto_grant_free',
-                planVersionId: 'starter-v1'
+                planId: 'starter'
             });
             const match = matchRoute('POST', '/api/taskforce/admin/system-settings', routes);
             const req = createMockReq('POST', '/api/taskforce/admin/system-settings', {
@@ -11161,7 +12814,7 @@ describe('Server Routes', () => {
             await match?.handler(req, res, {});
             expect(core.validateOnboardingPolicy).toHaveBeenCalledWith({
                 mode: 'auto_grant_free',
-                planVersionId: 'starter-v1'
+                planId: 'starter'
             });
             expect(core.updateGlobalSettings).toHaveBeenCalledWith({
                 auth: {
@@ -11175,7 +12828,7 @@ describe('Server Routes', () => {
                 billing: {
                     onboardingPolicy: {
                         mode: 'auto_grant_free',
-                        planVersionId: 'starter-v1'
+                        planId: 'starter'
                     }
                 }
             });
@@ -11288,13 +12941,13 @@ describe('Server Routes', () => {
         it('POST /api/taskforce/admin/system-settings should reject invalid onboarding settings', async () => {
             core.validateOnboardingPolicy.mockReturnValueOnce({
                 valid: false,
-                code: 'ONBOARDING_PLAN_VERSION_REQUIRED',
-                message: 'An onboarding plan version is required for the selected onboarding mode.'
+                code: 'ONBOARDING_PLAN_REQUIRED',
+                message: 'An onboarding plan is required for the selected onboarding mode.'
             });
             const match = matchRoute('POST', '/api/taskforce/admin/system-settings', routes);
             const req = createMockReq('POST', '/api/taskforce/admin/system-settings', {
                 onboardingPolicyMode: 'auto_grant_free',
-                onboardingPlanVersionId: null
+                onboardingPlanId: null
             }, { 'x-taskforce-role': 'admin' });
             const res = createMockRes();
             await match?.handler(req, res, {});