@taskforcehq/taskforce 0.3.305 → 0.3.307

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();
@@ -133,6 +138,7 @@ vi.mock('../core/Taskforce', () => {
             listMcpAccessTokens = vi.fn().mockReturnValue({ items: [], total: 0, page: 1, pageSize: 20 });
             createMcpAccessToken = vi.fn();
             revokeMcpAccessToken = vi.fn();
+            deleteMcpAccessToken = vi.fn();
             regenerateMcpAccessToken = vi.fn();
             inspectMcpAccessToken = vi.fn();
             authenticateMcpAccessToken = vi.fn();
@@ -156,12 +162,17 @@ 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();
+            updateAiProfileAvatar = vi.fn();
             replaceWorkspaceUsersForSync = vi.fn().mockReturnValue([]);
             listDocumentReviewSessionsForSync = vi.fn().mockReturnValue([]);
             listDocumentReviewCommentsForSync = vi.fn().mockReturnValue([]);
             listAnnotatedAttachmentSessionsForSync = vi.fn().mockReturnValue([]);
             listTaskEventsForSync = vi.fn().mockReturnValue([]);
             listTaskEvents = vi.fn().mockReturnValue([]);
+            recordTaskEvent = vi.fn();
             getDocumentReviewSession = vi.fn().mockReturnValue(null);
             upsertAiProfileForSync = vi.fn();
             upsertDocumentReviewSessionForSync = vi.fn();
@@ -235,6 +246,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 +423,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 +636,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 +718,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 +740,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, {
@@ -779,13 +832,15 @@ describe('Server Routes', () => {
             }));
             expect(res.end).toHaveBeenCalledWith();
         });
-        it('POST /mcp should accept authenticated initialize requests and record token usage', async () => {
+        it('POST /mcp should accept authenticated initialize requests, record token usage, and close the request runtime', async () => {
+            const serverClose = vi.fn().mockResolvedValue(undefined);
             const createServerSpy = vi.spyOn(mcpRuntime, 'createTaskforceMcpServer').mockReturnValue({
                 server: {
                     connect: vi.fn().mockResolvedValue(undefined),
-                    close: vi.fn().mockResolvedValue(undefined)
+                    close: serverClose
                 }
             });
+            const closeTransportSpy = vi.spyOn(StreamableHTTPServerTransport.prototype, 'close').mockResolvedValue(undefined);
             const handleRequestSpy = vi.spyOn(StreamableHTTPServerTransport.prototype, 'handleRequest').mockImplementation(async (_req, res, parsedBody) => {
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({
@@ -828,6 +883,8 @@ describe('Server Routes', () => {
             expect(match).not.toBeNull();
             await match.handler(req, res, match.params);
             expect(core.authenticateMcpAccessToken).toHaveBeenCalledWith('tfmcp_test_token');
+            const runtimeOptions = createServerSpy.mock.calls[0]?.[0];
+            expect(runtimeOptions?.core).toBe(core);
             expect(createServerSpy).toHaveBeenCalledWith(expect.objectContaining({
                 workspaceId: 'workspace-1',
                 runtimeMode: 'cloud',
@@ -857,6 +914,62 @@ describe('Server Routes', () => {
                     })
                 })
             }));
+            expect(closeTransportSpy).not.toHaveBeenCalled();
+            expect(serverClose).toHaveBeenCalledTimes(1);
+            closeTransportSpy.mockRestore();
+            handleRequestSpy.mockRestore();
+            createServerSpy.mockRestore();
+        });
+        it('POST /mcp should distinguish transport failures from tool backend failures', async () => {
+            const serverClose = vi.fn().mockResolvedValue(undefined);
+            const createServerSpy = vi.spyOn(mcpRuntime, 'createTaskforceMcpServer').mockReturnValue({
+                server: {
+                    connect: vi.fn().mockResolvedValue(undefined),
+                    close: serverClose
+                }
+            });
+            const handleRequestSpy = vi.spyOn(StreamableHTTPServerTransport.prototype, 'handleRequest').mockRejectedValue(new Error('transport broke'));
+            const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            core.authenticateMcpAccessToken.mockReturnValue({
+                tokenId: 'token-transport-1',
+                userId: 'user-1',
+                workspaceId: 'workspace-1',
+                scopes: ['tasks:read', 'workspace:read'],
+                status: 'active'
+            });
+            const match = matchRoute('POST', '/mcp', routes);
+            const req = createMockReq('POST', '/mcp', {
+                jsonrpc: '2.0',
+                id: 2,
+                method: 'tools/call',
+                params: {
+                    name: 'get_workstream',
+                    arguments: { id: 'WS-1' }
+                }
+            }, {
+                'x-taskforce-runtime-mode': 'cloud',
+                authorization: 'Bearer tfmcp_transport_token',
+                accept: 'application/json, text/event-stream',
+                'content-type': 'application/json',
+                'x-request-id': 'req-mcp-transport'
+            });
+            const res = createMockRes();
+            expect(match).not.toBeNull();
+            await match.handler(req, res, match.params);
+            expect(res.statusCode).toBe(500);
+            expect(JSON.parse(res.__getBody())).toEqual(expect.objectContaining({
+                jsonrpc: '2.0',
+                error: expect.objectContaining({
+                    message: 'MCP transport failure.',
+                    data: expect.objectContaining({
+                        kind: 'tool_transport_failure',
+                        retryable: true,
+                        requestId: 'req-mcp-transport'
+                    })
+                })
+            }));
+            expect(serverClose).toHaveBeenCalledTimes(1);
+            consoleErrorSpy.mockRestore();
             handleRequestSpy.mockRestore();
             createServerSpy.mockRestore();
         });
@@ -1040,7 +1153,10 @@ describe('Server Routes', () => {
                 clientId: 'client-1',
                 provider: 'chatgpt',
                 scopes: ['tasks:read'],
-                status: 'active'
+                status: 'active',
+                aiProfileId: 'ai-profile-1',
+                aiProfileToken: 'tfp_connector_codex',
+                aiProfileName: 'Codex Connector'
             });
             const match = matchRoute('POST', '/mcp', routes);
             const req = createMockReq('POST', '/mcp', {
@@ -1068,7 +1184,9 @@ describe('Server Routes', () => {
                     scopes: ['tasks:read'],
                     actorType: 'oauth',
                     tokenId: 'grant-1',
-                    userId: 'user-oauth'
+                    userId: 'user-oauth',
+                    aiProfileToken: 'tfp_connector_codex',
+                    aiProfileName: 'Codex Connector'
                 })
             }));
             handleRequestSpy.mockRestore();
@@ -1522,6 +1640,43 @@ describe('Server Routes', () => {
                 items: expect.any(Array)
             }));
         });
+        it('DELETE /api/taskforce/settings/mcp/tokens/:id should delete an inactive token for the signed-in user', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'workspace-1',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.deleteMcpAccessToken.mockReturnValue(true);
+            const cookie = createSessionTokenCookie('session-mcp-token-delete', authConfig, {
+                role: 'member',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            const match = matchRoute('DELETE', '/api/taskforce/settings/mcp/tokens/token-1', routes);
+            const req = createMockReq('DELETE', '/api/taskforce/settings/mcp/tokens/token-1', undefined, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud'
+            });
+            const res = createMockRes();
+            expect(match).not.toBeNull();
+            await match.handler(req, res, { id: 'token-1' });
+            expect(core.deleteMcpAccessToken).toHaveBeenCalledWith({
+                actorUserId: 'user-1',
+                workspaceId: 'workspace-1',
+                tokenId: 'token-1'
+            });
+            expect(JSON.parse(res.__getBody())).toEqual({
+                success: true,
+                deleted: true
+            });
+        });
         it('POST /api/taskforce/global-settings should update global settings', async () => {
             const payload = { theme: 'light', shortcut: 'Ctrl+Shift+L' };
             const match = matchRoute('POST', '/api/taskforce/global-settings', routes);
@@ -1589,6 +1744,49 @@ describe('Server Routes', () => {
             });
             expect(getAfterRes.end).toHaveBeenCalledWith(expect.stringContaining('"sourceOfTruth":"cloud"'));
         });
+        it('POST /api/taskforce/ui-state should accept large workspace-sync baselines', async () => {
+            const match = matchRoute('POST', '/api/taskforce/ui-state', routes);
+            const largeWatermark = 'x'.repeat(1024 * 1024 + 1);
+            const req = createMockReq('POST', '/api/taskforce/ui-state', {
+                stateKey: 'workspace-sync',
+                workspaceId: 'workspace-large-baseline',
+                patch: {
+                    version: 2,
+                    enabled: true,
+                    phase: 'active',
+                    pushBaseline: {
+                        taskIds: ['task-1'],
+                        taskWatermarks: [['task-1', largeWatermark]],
+                        taskChangeKeys: [],
+                        initiativeWatermarks: [],
+                        workstreamWatermarks: [],
+                        aiProfileWatermarks: [],
+                        aiProfileChangeKeys: [],
+                        documentWatermarks: [],
+                        assetWatermarks: [],
+                        documentReviewSessionWatermarks: [],
+                        documentReviewCommentWatermarks: [],
+                        annotatedAttachmentSessionWatermarks: [],
+                        taskEventWatermarks: [],
+                        taxonomyStateFingerprint: ''
+                    }
+                }
+            }, {
+                'x-taskforce-runtime-mode': 'local',
+                'x-taskforce-workspace-id': 'workspace-current'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(core.updateUiState).toHaveBeenCalledWith('workspace-large-baseline', 'anonymous', {
+                stateKey: 'workspace-sync',
+                patch: expect.objectContaining({
+                    pushBaseline: expect.objectContaining({
+                        taskWatermarks: [['task-1', largeWatermark]]
+                    })
+                })
+            });
+        });
         it('GET /api/taskforce/ui-state should ignore query workspace overrides in cloud mode', async () => {
             core.getUiState.mockReturnValue({ activeWorkspaceModule: 'tasks' });
             const match = matchRoute('GET', '/api/taskforce/ui-state', routes);
@@ -2157,6 +2355,140 @@ 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 serve synced local AI avatars when R2 object is missing', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-ai-avatar-r2-fallback-'));
+            const projectRoot = fs.realpathSync(tmpRoot);
+            const basePath = path.join(projectRoot, '.taskforce');
+            const relativePath = 'workspaces/workspace-1/assets/images/ai-profiles/ai-profile-codex/avatar/asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-cropped.webp';
+            const absolutePath = path.join(basePath, relativePath);
+            fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+            fs.writeFileSync(absolutePath, Buffer.from('synced-ai-avatar'));
+            core.getPaths.mockReturnValue({ projectRoot, basePath });
+            const fetchMock = vi.fn().mockResolvedValue(new Response('', { status: 404 }));
+            vi.stubGlobal('fetch', fetchMock);
+            try {
+                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(relativePath);
+                const req = createMockReq('GET', `/api/taskforce/context/${encoded}`);
+                const res = createMockRes();
+                await matchRoute('GET', `/api/taskforce/context/${encoded}`, routesWithStorage)?.handler(req, res, { filename: encoded });
+                expect(fetchMock).toHaveBeenCalled();
+                expect(res.writeHead).toHaveBeenCalledWith(200, expect.objectContaining({
+                    'Content-Type': 'image/webp',
+                    'Content-Disposition': 'inline'
+                }));
+                expect(String(res.getHeader('location') || '')).toBe('');
+                expect(res.__getBody()).toBe('synced-ai-avatar');
+            }
+            finally {
+                vi.unstubAllGlobals();
+                fs.rmSync(tmpRoot, { recursive: true, force: true });
+            }
+        });
+        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,
@@ -3075,6 +3407,53 @@ describe('Server Routes', () => {
             vi.unstubAllGlobals();
             fs.rmSync(tmpRoot, { recursive: true, force: true });
         });
+        it('POST /api/taskforce/context-upload/finalize should record direct AI avatar uploads instead of fast-finalizing', async () => {
+            const fetchMock = vi.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: 'OK',
+                headers: { get: () => 'image/webp' },
+                arrayBuffer: async () => new TextEncoder().encode('avatar-bytes').buffer
+            });
+            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 relativePath = 'workspaces/workspace-1/assets/images/ai-profiles/ai-profile-codex/avatar/asset-avatar.webp';
+            const match = matchRoute('POST', '/api/taskforce/context-upload/finalize', routesWithStorage);
+            const req = createMockReq('POST', '/api/taskforce/context-upload/finalize', {
+                relativePath,
+                mimeType: 'image/webp',
+                originalName: 'avatar.webp',
+                fastFinalize: true
+            }, {
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(fetchMock).toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(200, { 'Content-Type': 'application/json' });
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload).toEqual(expect.objectContaining({
+                success: true,
+                fsPath: relativePath,
+                path: `/api/taskforce/context/${encodeURIComponent(relativePath)}`
+            }));
+            expect(payload.mode).not.toBe('direct-fast');
+            vi.unstubAllGlobals();
+        });
         it('POST /api/taskforce/context-upload/finalize should mirror upload metadata into workspace_assets', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-context-finalize-canonical-'));
             core.getPaths.mockReturnValue({
@@ -3108,8 +3487,21 @@ describe('Server Routes', () => {
                 }
             });
             const match = matchRoute('POST', '/api/taskforce/context-upload/finalize', routesWithStorage);
+            const attachmentPath = '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Ffiles%2Fasset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-spec.pdf';
+            const attachmentFsPath = 'workspaces/workspace-1/assets/files/asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-spec.pdf';
+            core.getTask
+                .mockImplementationOnce(() => ({ id: 'task-1', attachments: [] }))
+                .mockImplementationOnce(() => ({
+                id: 'task-1',
+                attachments: [{
+                        path: attachmentPath,
+                        fsPath: attachmentFsPath,
+                        caption: 'spec.pdf',
+                        assetId: 'asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+                    }]
+            }));
             const req = createMockReq('POST', '/api/taskforce/context-upload/finalize', {
-                relativePath: 'workspaces/workspace-1/assets/files/asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-spec.pdf',
+                relativePath: attachmentFsPath,
                 mimeType: 'application/pdf',
                 taskId: 'task-1',
                 originalName: 'spec.pdf'
@@ -3121,8 +3513,8 @@ describe('Server Routes', () => {
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload).toEqual(expect.objectContaining({
                 success: true,
-                path: '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Ffiles%2Fasset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-spec.pdf',
-                fsPath: 'workspaces/workspace-1/assets/files/asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-spec.pdf',
+                path: attachmentPath,
+                fsPath: attachmentFsPath,
                 taskId: 'task-1'
             }));
             const assets = store.listByWorkspace('workspace-1', { includeDeleted: true });
@@ -3136,6 +3528,25 @@ describe('Server Routes', () => {
             expect(store.listLinksForTask('task-1', 'workspace-1')).toEqual([
                 expect.objectContaining({ role: 'attachment' })
             ]);
+            expect(core.recordTaskEvent).toHaveBeenCalledWith(expect.objectContaining({
+                taskId: 'task-1',
+                workspaceId: 'workspace-1',
+                action: 'task-attachments-changed',
+                actor: 'user',
+                createdAt: expect.any(String),
+                details: {
+                    changes: {
+                        attachments: {
+                            from: [],
+                            to: [expect.objectContaining({
+                                    path: attachmentPath,
+                                    fsPath: attachmentFsPath,
+                                    assetId: 'asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+                                })],
+                        },
+                    },
+                },
+            }));
             vi.unstubAllGlobals();
             fs.rmSync(dbRoot, { recursive: true, force: true });
             fs.rmSync(tmpRoot, { recursive: true, force: true });
@@ -3447,6 +3858,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,8 +4001,8 @@ describe('Server Routes', () => {
             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-'));
+        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'),
@@ -3553,29 +4011,142 @@ describe('Server Routes', () => {
             core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
             core.getTenantId = vi.fn().mockReturnValue('default');
             store.upsertAsset({
-                assetId: 'asset-doc-sparse-1',
-                workspaceId: 'workspace-1',
+                assetId: 'asset-doc-generic-link-1',
+                workspaceId: 'default',
                 kind: 'document',
-                logicalName: 'asset-doc-sparse-1',
-                originalFilename: 'asset-doc-sparse-1-implementation-plan-1773922162143.md',
+                originalFilename: 'shared-notes.md',
                 mimeType: 'text/markdown',
-                storageProvider: 'r2',
-                storageKey: 'workspaces/workspace-1/assets/documents/asset-doc-sparse-1-implementation-plan-1773922162143.md',
-                contentSha256: 'sha-doc-sparse-1',
-                sizeBytes: 222,
-                documentId: 'doc-sparse-1',
+                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-18T15:00:00.000Z'
+                updatedAt: '2026-03-18T13:30:00.000Z'
             });
             store.upsertLink({
-                workspaceId: 'workspace-1',
-                assetId: 'asset-doc-sparse-1',
-                taskId: 'task-sparse-1',
-                role: 'attachment',
-                displayName: 'AI Profiles - Implementation Plan v2'
+                workspaceId: 'default',
+                assetId: 'asset-doc-generic-link-1',
+                targetType: 'initiative',
+                targetId: 'initiative-1',
+                role: 'attachment'
             });
-            core.getTask.mockImplementation((id) => id === 'task-sparse-1'
-                ? { id: 'task-sparse-1', title: 'Task Sparse 1' }
+            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 () => {
+            vi.useFakeTimers();
+            vi.setSystemTime(new Date('2026-03-18T14:45:00.000Z'));
+            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();
+            try {
+                await match?.handler(req, res, { assetId: 'asset-doc-attach-route-1' });
+            }
+            finally {
+                vi.useRealTimers();
+            }
+            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',
+                        timestamp: '2026-03-18T14:45:00.000Z',
+                    })
+                ]
+            }), '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({
+                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-sparse-1',
+                workspaceId: 'workspace-1',
+                kind: 'document',
+                logicalName: 'asset-doc-sparse-1',
+                originalFilename: 'asset-doc-sparse-1-implementation-plan-1773922162143.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'r2',
+                storageKey: 'workspaces/workspace-1/assets/documents/asset-doc-sparse-1-implementation-plan-1773922162143.md',
+                contentSha256: 'sha-doc-sparse-1',
+                sizeBytes: 222,
+                documentId: 'doc-sparse-1',
+                version: 1,
+                updatedAt: '2026-03-18T15:00:00.000Z'
+            });
+            store.upsertLink({
+                workspaceId: 'workspace-1',
+                assetId: 'asset-doc-sparse-1',
+                taskId: 'task-sparse-1',
+                role: 'attachment',
+                displayName: 'AI Profiles - Implementation Plan v2'
+            });
+            core.getTask.mockImplementation((id) => id === 'task-sparse-1'
+                ? { id: 'task-sparse-1', title: 'Task Sparse 1' }
                 : null);
             const routesWithDb = createRoutes(core, {
                 authConfig: { runtimeMode: 'cloud' }
@@ -4559,6 +5130,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 +5254,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 +5269,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 +5602,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 +6496,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 +6513,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 +6587,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 () => {
@@ -6063,6 +6722,58 @@ describe('Server Routes', () => {
             ]));
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
+        it('GET /api/taskforce/sync/workspace/assets should include AI profile avatar files referenced without canonical metadata', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-ai-avatar-assets-'));
+            const projectRoot = fs.realpathSync(tmpRoot);
+            const basePath = path.join(tmpRoot, '.taskforce');
+            const avatarStorageKey = 'workspaces/workspace-local/assets/images/ai-profiles/ai-profile-codex/avatar/asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-cropped.webp';
+            const avatarDir = path.join(basePath, 'workspaces/workspace-local/assets/images/ai-profiles/ai-profile-codex/avatar');
+            fs.mkdirSync(avatarDir, { recursive: true });
+            const fileBuffer = Buffer.from('ai-avatar-bytes');
+            fs.writeFileSync(path.join(avatarDir, 'asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-cropped.webp'), fileBuffer);
+            const { tmpRoot: dbRoot, db } = createWorkspaceAssetTestStore();
+            core.getPaths.mockReturnValue({
+                projectRoot,
+                basePath,
+            });
+            core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            core.listAiProfiles.mockReturnValue([
+                {
+                    id: 'ai-profile-codex',
+                    workspaceId: 'workspace-local',
+                    name: 'Codex',
+                    username: 'codex',
+                    avatarUrl: `/api/taskforce/context/${encodeURIComponent(avatarStorageKey)}`,
+                    avatarSourceUrl: null,
+                    createdAt: '2026-03-17T09:00:00.000Z',
+                    updatedAt: '2026-03-17T10:00:00.000Z'
+                }
+            ]);
+            routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            const match = matchRoute('GET', '/api/taskforce/sync/workspace/assets', routes);
+            const req = createMockReq('GET', '/api/taskforce/sync/workspace/assets?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.knownPaths).toContain(avatarStorageKey);
+            expect(payload.assets).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    path: avatarStorageKey,
+                    assetId: 'asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+                    kind: 'image',
+                    mimeType: 'image/webp',
+                    originalFilename: 'asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-cropped.webp',
+                    contentBase64: fileBuffer.toString('base64')
+                })
+            ]));
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
         it('GET /api/taskforce/sync/workspace/assets should ignore malformed external workspace asset rows', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-assets-external-'));
             const projectRoot = fs.realpathSync(tmpRoot);
@@ -6729,6 +7440,82 @@ describe('Server Routes', () => {
             ]));
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
+        it('GET /api/taskforce/sync/workspace/pull should include referenced AI profile avatar assets without canonical metadata', 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 = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-pull-ai-avatar-'));
+            const basePath = path.join(tmpRoot, '.taskforce');
+            const avatarStorageKey = 'workspaces/workspace-1/assets/images/ai-profiles/ai-profile-modesty/avatar/asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-cropped.webp';
+            const avatarPath = path.join(basePath, avatarStorageKey);
+            const avatarBuffer = Buffer.from('ai-avatar-bytes');
+            fs.mkdirSync(path.dirname(avatarPath), { recursive: true });
+            fs.writeFileSync(avatarPath, avatarBuffer);
+            const { tmpRoot: dbRoot, db } = createWorkspaceAssetTestStore();
+            core.getPaths.mockReturnValue({
+                projectRoot: tmpRoot,
+                basePath,
+            });
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            core.listAiProfiles.mockReturnValue([
+                {
+                    id: 'ai-profile-modesty',
+                    workspaceId: 'workspace-1',
+                    name: 'Modesty',
+                    username: 'modesty',
+                    icon: 'Bot',
+                    color: '#0ea5e9',
+                    avatarUrl: `/api/taskforce/context/${encodeURIComponent(avatarStorageKey)}`,
+                    avatarSourceUrl: null,
+                    createdAt: '2026-03-17T09:00:00.000Z',
+                    updatedAt: '2026-03-17T10:00:00.000Z'
+                }
+            ]);
+            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-ai-avatar', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            core.listTasks.mockReturnValueOnce({ tasks: [] });
+            core.listArchive.mockReturnValueOnce({ archived: [] });
+            const match = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+            const req = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-1&limit=20', undefined, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payload = JSON.parse(String(res.end.mock.calls[0]?.[0] || '{}'));
+            expect(payload.changes).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    op: 'ai-profile-upsert',
+                    profile: expect.objectContaining({
+                        id: 'ai-profile-modesty',
+                        avatarUrl: `/api/taskforce/context/${encodeURIComponent(avatarStorageKey)}`
+                    })
+                }),
+                expect.objectContaining({
+                    op: 'asset-upsert',
+                    path: avatarStorageKey,
+                    assetId: 'asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+                    kind: 'image',
+                    mimeType: 'image/webp',
+                    originalFilename: 'asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-cropped.webp',
+                    linkRole: 'image',
+                    contentBase64: avatarBuffer.toString('base64')
+                })
+            ]));
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
         it('GET /api/taskforce/sync/workspace/pull should include mixed document and binary attachment upserts for the same task', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -7086,7 +7873,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,21 +7886,179 @@ 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-1&limit=10&cursor=not-a-real-cursor', undefined, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            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-invalid-cursor'
+            }));
+        });
+        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 degrade optional snapshot failures into diagnostics instead of 500', 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 }]);
+            core.listTasks.mockReturnValueOnce({
+                tasks: [
+                    {
+                        id: 'task-survives',
+                        title: 'Survives partial feed failure',
+                        status: 'task',
+                        category: 'general',
+                        type: 'task',
+                        createdAt: '2026-04-10T10:00:00.000Z'
+                    }
+                ]
+            });
+            core.listDocumentReviewSessionsForSync.mockImplementationOnce(() => {
+                throw new Error('document review session snapshot exploded');
+            });
+            const cookie = createSessionTokenCookie('session-sync-pull-partial', 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', undefined, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const body = JSON.parse(String(res.end.mock.calls[0]?.[0] || '{}'));
+            expect(body.success).toBe(true);
+            expect(body.changes).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    op: 'upsert',
+                    task: expect.objectContaining({ id: 'task-survives' })
+                })
+            ]));
+            expect(body.diagnostics?.snapshotErrors).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    domain: 'document-review-sessions',
+                    error: 'document review session snapshot exploded'
+                })
+            ]));
+        });
+        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 });
@@ -7147,6 +8092,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 +8883,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 +8937,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 +9000,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 +9052,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 +9379,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,101 +9391,299 @@ 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([
+        });
+        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 })
             ]));
@@ -9417,11 +10607,11 @@ 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 be disabled in local runtime', async () => {
+        it('POST /api/taskforce/session/workspace should allow a read-only user to switch to another active workspace', async () => {
             const authConfig = {
-                runtimeMode: 'local',
+                runtimeMode: 'cloud',
                 enabled: true,
-                requiredForApi: false,
+                requiredForApi: true,
                 excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
                 defaultRole: 'member',
                 defaultWorkspaceId: 'default',
@@ -9430,13 +10620,134 @@ describe('Server Routes', () => {
                 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-2'
+                workspaceId: 'workspace-home'
+            }, {
+                cookie
             });
             const res = createMockRes();
+            res.setHeader = vi.fn();
             await match?.handler(req, res, {});
-            expect(res.writeHead).toHaveBeenCalledWith(501, expect.any(Object));
+            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',
+                enabled: true,
+                requiredForApi: false,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            const match = matchRoute('POST', '/api/taskforce/session/workspace', routes);
+            const req = createMockReq('POST', '/api/taskforce/session/workspace', {
+                workspaceId: 'workspace-2'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(501, expect.any(Object));
             expect(res.end).toHaveBeenCalledWith(expect.stringContaining('Workspace switching is unavailable in local mode.'));
             expect(core.listUserWorkspaces).not.toHaveBeenCalled();
         });
@@ -9512,7 +10823,10 @@ describe('Server Routes', () => {
             await match?.handler(req, res, {});
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.authenticated).toBe(true);
+            expect(payload.authRequiredForApi).toBe(true);
+            expect(payload.runtimeMode).toBe('cloud');
             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 +11037,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 +11229,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 +11355,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 +11461,7 @@ 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'
@@ -10015,7 +11482,75 @@ describe('Server Routes', () => {
                 workspaceRole: 'owner',
                 canManageWorkspace: true,
                 teamPlanMode: 'personal',
-                teamManagementAllowed: false
+                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'
+            });
+            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: null,
+                planVersionId: null,
+                entitlementState: null,
+                gate: 'missing_entitlement',
+                message: 'No entitlement is linked to this account.',
+                planSelectionRequired: 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 +11622,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 +11743,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 +11787,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 +11799,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 +11839,7 @@ describe('Server Routes', () => {
             expect(core.upsertPlanCatalog).toHaveBeenCalledWith({
                 planId: 'enterprise',
                 displayName: 'Enterprise',
+                description: undefined,
                 status: 'active',
                 initialTrialDays: 0,
                 initialMode: undefined,
@@ -10286,15 +11859,51 @@ describe('Server Routes', () => {
             expect(core.listPlanCatalog).toHaveBeenCalled();
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
-        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, {
+        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, { planId: 'collab' });
-            expect(core.listPlanVersions).toHaveBeenCalledWith('collab');
+            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, {
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-system-role': 'system_admin'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { planId: 'collab' });
+            expect(core.listPlanVersions).toHaveBeenCalledWith('collab');
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
         it('POST /api/platform/plans/:planId/versions should forward per-version trial days', async () => {
@@ -10344,6 +11953,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 +12113,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 +12152,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 +12415,268 @@ 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();
+            expect(matchRoute('POST', '/api/taskforce/workspace/ai-profiles/avatar/upload', routes)).not.toBeNull();
+            expect(matchRoute('POST', '/api/taskforce/workspace/ai-profiles/metadata', routes)).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 +12771,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 +12793,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 +12817,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 +12835,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,19 +12845,104 @@ describe('Server Routes', () => {
                     username: 'codex',
                     icon: 'Bot',
                     color: '#ef6c00',
+                    avatarUrl: null,
+                    avatarSourceUrl: null,
+                    avatarRevision: 0,
+                    avatarUpdatedAt: 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
+                }
+            ]);
+        });
+        it('GET /api/taskforce/workspace/assignee-options should support agent-only roster loads', 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.listWorkspaceUsers.mockReturnValue([
+                {
+                    userId: 'member-1',
+                    email: 'member1@example.com',
+                    displayName: 'Member One',
+                    avatarUrl: null,
+                    role: 'member',
+                    permissionMode: 'read-write',
+                    betaAccess: true,
+                    status: 'active',
+                    disabled: false
+                }
+            ]);
+            core.listAiProfiles.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',
+                    seatScope: 'cloud_metered',
+                    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-agent-roster', authConfig, {
+                userId: 'member-user',
+                role: 'member',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('GET', '/api/taskforce/workspace/assignee-options?kind=agent', undefined, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'member',
+                'x-taskforce-user-id': 'member-user',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.listWorkspaceUsers).not.toHaveBeenCalled();
+            expect(core.listAiProfiles).toHaveBeenCalledWith('workspace-1', expect.objectContaining({
+                diagnostics: expect.any(Object)
+            }));
+            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: 1, limit: 3, remaining: 2 });
+            expect(payload.assignees).toEqual([
+                expect.objectContaining({
+                    value: 'ai-profile-1',
+                    label: 'Codex',
+                    kind: 'agent'
+                })
+            ]);
         });
-        it('GET /api/taskforce/workspace/assignee-options should include ai profile tokens for workspace admins', async () => {
+        it('GET /api/taskforce/workspace/assignee-options should not include ai profile tokens for workspace admins', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
                 enabled: true,
@@ -10970,6 +12975,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,12 +12992,384 @@ 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',
-                    profileToken: 'tfp_codex_sync'
+                    label: 'Codex'
                 })
             ]);
+            expect(payload.assignees[0]).not.toHaveProperty('profileToken');
+        });
+        it('POST /api/taskforce/workspace/ai-profiles/avatar should reject direct avatar URL writes', 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 match = matchRoute('POST', '/api/taskforce/workspace/ai-profiles/avatar', routes);
+            const cookie = createSessionTokenCookie('session-admin-avatar-ai-profile-reject', authConfig, {
+                userId: 'admin-user',
+                role: 'admin',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('POST', '/api/taskforce/workspace/ai-profiles/avatar', {
+                profileId: 'ai-profile-1',
+                avatarUrl: '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fai-profiles%2Favatar.webp'
+            }, {
+                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.updateAiProfileAvatar).not.toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload).toEqual({
+                error: 'AI profile avatar updates must use the stable avatar upload endpoint.',
+                code: 'AI_PROFILE_AVATAR_STABLE_UPLOAD_REQUIRED'
+            });
+        });
+        it('POST /api/taskforce/workspace/ai-profiles/avatar should allow clear-only updates and redact profile tokens', 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.listAiProfiles.mockReturnValue([
+                {
+                    id: 'ai-profile-1',
+                    workspaceId: 'workspace-1',
+                    avatarUrl: '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fai-profiles%2Fai-profile-1%2Favatar%2Fdisplay.webp',
+                    avatarSourceUrl: '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fai-profiles%2Fai-profile-1%2Favatar%2Fsource.webp'
+                }
+            ]);
+            core.updateAiProfileAvatar.mockReturnValue({
+                id: 'ai-profile-1',
+                workspaceId: 'workspace-1',
+                profileToken: 'tfp_codex_sync',
+                name: 'Codex',
+                username: 'codex',
+                icon: 'Bot',
+                color: '#ef6c00',
+                avatarUrl: null,
+                avatarSourceUrl: null,
+                description: 'Builds product code',
+                role: 'Implementer',
+                provider: 'OpenAI',
+                model: 'gpt-5.4',
+                surfaceType: 'coding_tool',
+                archivedAt: 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/avatar', routes);
+            const cookie = createSessionTokenCookie('session-admin-avatar-ai-profile-clear', authConfig, {
+                userId: 'admin-user',
+                role: 'admin',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('POST', '/api/taskforce/workspace/ai-profiles/avatar', {
+                profileId: 'ai-profile-1',
+                avatarUrl: null,
+                avatarSourceUrl: null
+            }, {
+                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.updateAiProfileAvatar).toHaveBeenCalledWith({
+                workspaceId: 'workspace-1',
+                profileId: 'ai-profile-1',
+                avatarUrl: null,
+                avatarSourceUrl: null
+            });
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.success).toBe(true);
+            expect(payload.profile).toEqual(expect.objectContaining({
+                id: 'ai-profile-1',
+                avatarUrl: null,
+                avatarSourceUrl: null
+            }));
+            expect(payload.profile).not.toHaveProperty('profileToken');
+        });
+        it('POST /api/taskforce/workspace/ai-profiles/merge should redact profile tokens from admin responses', 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.mergeAiProfiles.mockReturnValue({
+                id: 'ai-profile-keep',
+                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: 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/merge', routes);
+            const cookie = createSessionTokenCookie('session-admin-merge-ai-profile', authConfig, {
+                userId: 'admin-user',
+                role: 'admin',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('POST', '/api/taskforce/workspace/ai-profiles/merge', {
+                keepId: 'ai-profile-keep',
+                mergeId: 'ai-profile-merge'
+            }, {
+                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.mergeAiProfiles).toHaveBeenCalledWith({
+                workspaceId: 'workspace-1',
+                keepId: 'ai-profile-keep',
+                mergeId: 'ai-profile-merge'
+            });
+            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-keep',
+                name: 'Codex'
+            }));
+            expect(payload.profile).not.toHaveProperty('profileToken');
+        });
+        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'
+            }));
+            expect(payload.profile).not.toHaveProperty('profileToken');
+        });
+        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 = {
@@ -11090,13 +13468,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 +13482,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 +13496,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 +13516,7 @@ describe('Server Routes', () => {
                 billing: {
                     onboardingPolicy: {
                         mode: 'auto_grant_free',
-                        planVersionId: 'starter-v1'
+                        planId: 'starter'
                     }
                 }
             });
@@ -11146,7 +13524,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 +13539,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 +13553,7 @@ describe('Server Routes', () => {
                 billing: {
                     onboardingPolicy: {
                         mode: 'auto_grant_free',
-                        planVersionId: 'starter-v1'
+                        planId: 'starter'
                     }
                 }
             });
@@ -11184,7 +13562,11 @@ describe('Server Routes', () => {
             core.getGlobalSettings.mockReturnValue({
                 site: {
                     showRunTaskforceLocally: false,
-                    pricingPageEnabled: false
+                    pricingPageEnabled: false,
+                    animatedBackgroundEnabled: true,
+                    siteTheme: 'light',
+                    pricingPageTitle: 'Choose Your Plan',
+                    pricingPageDescription: 'Compare plans and pick the right one.'
                 }
             });
             const match = matchRoute('GET', '/api/taskforce/admin/site-settings', routes);
@@ -11194,14 +13576,26 @@ describe('Server Routes', () => {
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.status.showRunTaskforceLocally).toBe(false);
             expect(payload.status.pricingPageEnabled).toBe(false);
+            expect(payload.status.animatedBackgroundEnabled).toBe(true);
+            expect(payload.status.siteTheme).toBe('light');
+            expect(payload.status.pricingPageTitle).toBe('Choose Your Plan');
+            expect(payload.status.pricingPageDescription).toBe('Compare plans and pick the right one.');
             expect(payload.settings.showRunTaskforceLocally).toBe(false);
             expect(payload.settings.pricingPageEnabled).toBe(false);
+            expect(payload.settings.animatedBackgroundEnabled).toBe(true);
+            expect(payload.settings.siteTheme).toBe('light');
+            expect(payload.settings.pricingPageTitle).toBe('Choose Your Plan');
+            expect(payload.settings.pricingPageDescription).toBe('Compare plans and pick the right one.');
         });
         it('GET /api/taskforce/admin/site_settings should expose effective website settings for legacy admin bundles', async () => {
             core.getGlobalSettings.mockReturnValue({
                 site: {
                     showRunTaskforceLocally: false,
-                    pricingPageEnabled: false
+                    pricingPageEnabled: false,
+                    animatedBackgroundEnabled: true,
+                    siteTheme: 'light',
+                    pricingPageTitle: 'Choose Your Plan',
+                    pricingPageDescription: 'Compare plans and pick the right one.'
                 }
             });
             const match = matchRoute('GET', '/api/taskforce/admin/site_settings', routes);
@@ -11211,21 +13605,37 @@ describe('Server Routes', () => {
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.status.showRunTaskforceLocally).toBe(false);
             expect(payload.status.pricingPageEnabled).toBe(false);
+            expect(payload.status.animatedBackgroundEnabled).toBe(true);
+            expect(payload.status.siteTheme).toBe('light');
+            expect(payload.status.pricingPageTitle).toBe('Choose Your Plan');
+            expect(payload.status.pricingPageDescription).toBe('Compare plans and pick the right one.');
             expect(payload.settings.showRunTaskforceLocally).toBe(false);
             expect(payload.settings.pricingPageEnabled).toBe(false);
+            expect(payload.settings.animatedBackgroundEnabled).toBe(true);
+            expect(payload.settings.siteTheme).toBe('light');
+            expect(payload.settings.pricingPageTitle).toBe('Choose Your Plan');
+            expect(payload.settings.pricingPageDescription).toBe('Compare plans and pick the right one.');
         });
         it('POST /api/taskforce/admin/site-settings should persist website settings', async () => {
             const match = matchRoute('POST', '/api/taskforce/admin/site-settings', routes);
             const req = createMockReq('POST', '/api/taskforce/admin/site-settings', {
                 showRunTaskforceLocally: false,
-                pricingPageEnabled: false
+                pricingPageEnabled: false,
+                animatedBackgroundEnabled: true,
+                siteTheme: 'light',
+                pricingPageTitle: 'Choose Your Plan',
+                pricingPageDescription: 'Compare plans and pick the right one.'
             }, { 'x-taskforce-role': 'admin' });
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.updateGlobalSettings).toHaveBeenCalledWith({
                 site: {
                     showRunTaskforceLocally: false,
-                    pricingPageEnabled: false
+                    pricingPageEnabled: false,
+                    animatedBackgroundEnabled: true,
+                    siteTheme: 'light',
+                    pricingPageTitle: 'Choose Your Plan',
+                    pricingPageDescription: 'Compare plans and pick the right one.'
                 }
             });
         });
@@ -11233,14 +13643,22 @@ describe('Server Routes', () => {
             const match = matchRoute('POST', '/api/taskforce/admin/site_settings', routes);
             const req = createMockReq('POST', '/api/taskforce/admin/site_settings', {
                 showRunTaskforceLocally: false,
-                pricingPageEnabled: false
+                pricingPageEnabled: false,
+                animatedBackgroundEnabled: true,
+                siteTheme: 'light',
+                pricingPageTitle: 'Choose Your Plan',
+                pricingPageDescription: 'Compare plans and pick the right one.'
             }, { 'x-taskforce-role': 'admin' });
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.updateGlobalSettings).toHaveBeenCalledWith({
                 site: {
                     showRunTaskforceLocally: false,
-                    pricingPageEnabled: false
+                    pricingPageEnabled: false,
+                    animatedBackgroundEnabled: true,
+                    siteTheme: 'light',
+                    pricingPageTitle: 'Choose Your Plan',
+                    pricingPageDescription: 'Compare plans and pick the right one.'
                 }
             });
         });
@@ -11248,7 +13666,11 @@ describe('Server Routes', () => {
             core.getGlobalSettings.mockReturnValue({
                 site: {
                     showRunTaskforceLocally: false,
-                    pricingPageEnabled: false
+                    pricingPageEnabled: false,
+                    animatedBackgroundEnabled: true,
+                    siteTheme: 'light',
+                    pricingPageTitle: 'Choose Your Plan',
+                    pricingPageDescription: 'Compare plans and pick the right one.'
                 }
             });
             const match = matchRoute('GET', '/api/taskforce/public/site-config', routes);
@@ -11263,7 +13685,11 @@ describe('Server Routes', () => {
                 success: true,
                 config: {
                     showRunTaskforceLocally: false,
-                    pricingPageEnabled: false
+                    pricingPageEnabled: false,
+                    animatedBackgroundEnabled: true,
+                    siteTheme: 'light',
+                    pricingPageTitle: 'Choose Your Plan',
+                    pricingPageDescription: 'Compare plans and pick the right one.'
                 }
             });
         });
@@ -11271,7 +13697,11 @@ describe('Server Routes', () => {
             core.getGlobalSettings.mockReturnValue({
                 site: {
                     showRunTaskforceLocally: false,
-                    pricingPageEnabled: false
+                    pricingPageEnabled: false,
+                    animatedBackgroundEnabled: true,
+                    siteTheme: 'light',
+                    pricingPageTitle: 'Choose Your Plan',
+                    pricingPageDescription: 'Compare plans and pick the right one.'
                 }
             });
             const match = matchRoute('GET', '/api/taskforce/public/site-config-script', routes);
@@ -11284,17 +13714,20 @@ describe('Server Routes', () => {
             }));
             expect(res.end.mock.calls[0][0]).toContain('window.__TASKFORCE_SITE_CONFIG__ = ');
             expect(res.end.mock.calls[0][0]).toContain('"pricingPageEnabled":false');
+            expect(res.end.mock.calls[0][0]).toContain('"animatedBackgroundEnabled":true');
+            expect(res.end.mock.calls[0][0]).toContain('"siteTheme":"light"');
+            expect(res.end.mock.calls[0][0]).toContain('"pricingPageTitle":"Choose Your Plan"');
         });
         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, {});
@@ -11460,6 +13893,94 @@ describe('Server Routes', () => {
             ]);
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
+        it('GET /api/taskforce/admin/orphaned-assets should not list AI profile avatar assets still referenced by profiles', async () => {
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            const avatarStorageKey = 'workspaces/workspace-1/assets/images/ai-profiles/ai-profile-codex/avatar/asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-cropped.webp';
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            core.listAiProfiles.mockReturnValueOnce([
+                {
+                    id: 'ai-profile-codex',
+                    workspaceId: 'workspace-1',
+                    name: 'Codex',
+                    avatarUrl: `/api/taskforce/context/${encodeURIComponent(avatarStorageKey)}`,
+                    avatarSourceUrl: null,
+                    createdAt: '2026-03-18T17:00:00.000Z',
+                    updatedAt: '2026-03-18T17:05:00.000Z'
+                }
+            ]);
+            store.upsertAsset({
+                assetId: 'asset-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+                workspaceId: 'workspace-1',
+                kind: 'image',
+                originalFilename: 'avatar.webp',
+                mimeType: 'image/webp',
+                storageProvider: 'r2',
+                storageKey: avatarStorageKey,
+                contentSha256: 'sha-avatar',
+                sizeBytes: 42,
+                createdAt: '2026-03-18T17:00:00.000Z',
+                updatedAt: '2026-03-18T17:05:00.000Z'
+            });
+            routes = createRoutes(core);
+            const match = matchRoute('GET', '/api/taskforce/admin/orphaned-assets', routes);
+            const req = createMockReq('GET', '/api/taskforce/admin/orphaned-assets?workspaceId=workspace-1', undefined, {
+                'x-taskforce-role': 'admin',
+                'x-taskforce-workspace-id': 'workspace-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.assets).toEqual([]);
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+        });
+        it('POST /api/taskforce/admin/orphaned-assets/delete should reject AI profile avatar assets still referenced by profiles', async () => {
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            const avatarStorageKey = 'workspaces/workspace-1/assets/images/ai-profiles/ai-profile-codex/avatar/asset-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb-cropped.webp';
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            core.listAiProfiles.mockReturnValueOnce([
+                {
+                    id: 'ai-profile-codex',
+                    workspaceId: 'workspace-1',
+                    name: 'Codex',
+                    avatarUrl: `/api/taskforce/context/${encodeURIComponent(avatarStorageKey)}`,
+                    avatarSourceUrl: null,
+                    createdAt: '2026-03-18T17:00:00.000Z',
+                    updatedAt: '2026-03-18T17:05:00.000Z'
+                }
+            ]);
+            store.upsertAsset({
+                assetId: 'asset-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+                workspaceId: 'workspace-1',
+                kind: 'image',
+                originalFilename: 'avatar.webp',
+                mimeType: 'image/webp',
+                storageProvider: 'r2',
+                storageKey: avatarStorageKey,
+                contentSha256: 'sha-avatar',
+                sizeBytes: 42,
+                createdAt: '2026-03-18T17:00:00.000Z',
+                updatedAt: '2026-03-18T17:05:00.000Z'
+            });
+            routes = createRoutes(core);
+            const match = matchRoute('POST', '/api/taskforce/admin/orphaned-assets/delete', routes);
+            const req = createMockReq('POST', '/api/taskforce/admin/orphaned-assets/delete', {
+                assetId: 'asset-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+                workspaceId: 'workspace-1'
+            }, {
+                'x-taskforce-role': 'admin',
+                '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).toMatch(/referenced by an AI profile avatar/i);
+            expect(store.get('asset-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb', 'workspace-1')?.deletedAt).toBeNull();
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+        });
         it('POST /api/taskforce/admin/object-storage-settings should persist sanitized values', async () => {
             const match = matchRoute('POST', '/api/taskforce/admin/object-storage-settings', routes);
             const req = createMockReq('POST', '/api/taskforce/admin/object-storage-settings', {