@taskforcehq/taskforce 0.3.306 → 0.3.308

package/dist/server/routes.test.js

@@ -138,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();
@@ -164,12 +165,14 @@ vi.mock('../core/Taskforce', () => {
             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();
@@ -829,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({
@@ -878,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',
@@ -907,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();
         });
@@ -1090,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', {
@@ -1118,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();
@@ -1572,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);
@@ -1639,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);
@@ -2242,6 +2390,50 @@ describe('Server Routes', () => {
             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;
@@ -3215,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({
@@ -3248,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'
@@ -3261,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 });
@@ -3276,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 });
@@ -3782,6 +4053,8 @@ describe('Server Routes', () => {
             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,
@@ -3817,7 +4090,12 @@ describe('Server Routes', () => {
                 'x-taskforce-workspace-id': 'default'
             });
             const res = createMockRes();
-            await match?.handler(req, res, { assetId: 'asset-doc-attach-route-1' });
+            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: [
@@ -3825,6 +4103,7 @@ describe('Server Routes', () => {
                         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({
@@ -6443,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);
@@ -7109,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',
@@ -7570,7 +7977,7 @@ describe('Server Routes', () => {
             expect(res.end).toHaveBeenCalledTimes(1);
             expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
         });
-        it('GET /api/taskforce/sync/workspace/pull should reject unauthorized workspace override', async () => {
+        it('GET /api/taskforce/sync/workspace/pull should degrade optional snapshot failures into diagnostics instead of 500', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
                 enabled: true,
@@ -7583,9 +7990,63 @@ describe('Server Routes', () => {
                 sessionTtlSeconds: 3600
             };
             routes = createRoutes(core, { authConfig });
-            const cookie = createSessionTokenCookie('session-sync-pull-forbidden', 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-cloud-selected',
+                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([
@@ -10362,6 +10823,8 @@ 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');
@@ -11343,7 +11806,8 @@ describe('Server Routes', () => {
                         label: null,
                         description: null,
                         publicLabel: null,
-                        publicDescription: null
+                        publicDescription: null,
+                        publicDescriptionVisible: false
                     }
                 ]);
             }
@@ -11497,6 +11961,7 @@ describe('Server Routes', () => {
                 description: 'Allow registered AI collaborator profiles with an optional per-workspace limit.',
                 publicLabel: 'AI teammates',
                 publicDescription: 'Add reusable AI teammates to your workspace.',
+                publicDescriptionVisible: false,
                 publicDisplayOrder: 20,
                 allowedAccessModes: ['enabled', 'limited', 'disabled'],
                 configTemplate: { maxAiProfiles: 1 }
@@ -11505,6 +11970,7 @@ describe('Server Routes', () => {
             const req = createMockReq('PATCH', '/api/platform/features/collaboration.ai_profiles', {
                 publicLabel: 'AI teammates',
                 publicDescription: 'Add reusable AI teammates to your workspace.',
+                publicDescriptionVisible: false,
                 publicDisplayOrder: 20
             }, {
                 'x-taskforce-runtime-mode': 'cloud',
@@ -11514,13 +11980,65 @@ describe('Server Routes', () => {
             await match?.handler(req, res, { featureKey: 'collaboration.ai_profiles' });
             expect(core.updatePlanFeatureCatalogMarketingCopy).toHaveBeenCalledWith({
                 featureKey: 'collaboration.ai_profiles',
+                label: undefined,
+                description: undefined,
                 publicLabel: 'AI teammates',
                 publicDescription: 'Add reusable AI teammates to your workspace.',
+                publicDescriptionVisible: false,
                 publicDisplayOrder: 20
             });
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"publicLabel":"AI teammates"'));
         });
+        it('POST /api/platform/features should create a custom feature catalog entry', async () => {
+            core.createCustomPlanFeatureCatalogEntry = vi.fn().mockReturnValue({
+                featureKey: 'marketing.unlimited_local_workspaces',
+                label: 'Unlimited Local Workspaces',
+                description: 'Run unlimited local workspaces on your device.',
+                isCustom: true,
+                publicLabel: null,
+                publicDescription: null,
+                publicDescriptionVisible: true,
+                publicDisplayOrder: 12,
+                allowedAccessModes: ['enabled', 'disabled'],
+                configTemplate: {}
+            });
+            const match = matchRoute('POST', '/api/platform/features', routes);
+            const req = createMockReq('POST', '/api/platform/features', {
+                label: 'Unlimited Local Workspaces',
+                description: 'Run unlimited local workspaces on your device.',
+                publicDescriptionVisible: true,
+                publicDisplayOrder: 12
+            }, {
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-system-role': 'system_admin'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.createCustomPlanFeatureCatalogEntry).toHaveBeenCalledWith({
+                label: 'Unlimited Local Workspaces',
+                description: 'Run unlimited local workspaces on your device.',
+                publicLabel: undefined,
+                publicDescription: undefined,
+                publicDescriptionVisible: true,
+                publicDisplayOrder: 12
+            });
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"featureKey":"marketing.unlimited_local_workspaces"'));
+        });
+        it('DELETE /api/platform/features/:featureKey should remove a custom feature catalog entry', async () => {
+            core.deleteCustomPlanFeatureCatalogEntry = vi.fn();
+            const match = matchRoute('DELETE', '/api/platform/features/marketing.unlimited_local_workspaces', routes);
+            const req = createMockReq('DELETE', '/api/platform/features/marketing.unlimited_local_workspaces', undefined, {
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-system-role': 'system_admin'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { featureKey: 'marketing.unlimited_local_workspaces' });
+            expect(core.deleteCustomPlanFeatureCatalogEntry).toHaveBeenCalledWith('marketing.unlimited_local_workspaces');
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
+        });
         it('PATCH /api/platform/plans/:planId/versions/:versionId/features should return normalized dependency state', async () => {
             core.updatePlanVersionFeatures.mockReturnValueOnce({
                 planVersionId: 'collab-v1',
@@ -11953,6 +12471,8 @@ describe('Server Routes', () => {
             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();
@@ -12382,6 +12902,8 @@ describe('Server Routes', () => {
                     color: '#ef6c00',
                     avatarUrl: null,
                     avatarSourceUrl: null,
+                    avatarRevision: 0,
+                    avatarUpdatedAt: null,
                     kind: 'agent',
                     description: 'Builds product code',
                     role: 'Implementer',
@@ -12396,7 +12918,86 @@ describe('Server Routes', () => {
                 }
             ]);
         });
-        it('GET /api/taskforce/workspace/assignee-options should include ai profile tokens for workspace admins', async () => {
+        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 not include ai profile tokens for workspace admins', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
                 enabled: true,
@@ -12450,9 +13051,187 @@ describe('Server Routes', () => {
             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 = {
@@ -12518,6 +13297,7 @@ describe('Server Routes', () => {
                 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 = {
@@ -12837,7 +13617,12 @@ 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.',
+                    pricingPageShowPublicDescriptions: false
                 }
             });
             const match = matchRoute('GET', '/api/taskforce/admin/site-settings', routes);
@@ -12847,14 +13632,29 @@ 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.status.pricingPageShowPublicDescriptions).toBe(false);
             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.');
+            expect(payload.settings.pricingPageShowPublicDescriptions).toBe(false);
         });
         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.',
+                    pricingPageShowPublicDescriptions: false
                 }
             });
             const match = matchRoute('GET', '/api/taskforce/admin/site_settings', routes);
@@ -12864,36 +13664,78 @@ 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.status.pricingPageShowPublicDescriptions).toBe(false);
             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.');
+            expect(payload.settings.pricingPageShowPublicDescriptions).toBe(false);
         });
         it('POST /api/taskforce/admin/site-settings should persist website settings', async () => {
             const match = matchRoute('POST', '/api/taskforce/admin/site-settings', routes);
+            const pricingPageDescription = `<p>${'Compare plans and pick the right one. '.repeat(12)}</p>`;
             const req = createMockReq('POST', '/api/taskforce/admin/site-settings', {
                 showRunTaskforceLocally: false,
-                pricingPageEnabled: false
+                pricingPageEnabled: false,
+                animatedBackgroundEnabled: true,
+                siteTheme: 'light',
+                pricingPageTitle: 'Choose Your Plan',
+                pricingPageDescription,
+                pricingPageShowPublicDescriptions: false
             }, { '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,
+                    pricingPageShowPublicDescriptions: false
                 }
             });
         });
+        it('POST /api/taskforce/admin/site-settings should reject pricing page descriptions over 2000 characters', async () => {
+            const match = matchRoute('POST', '/api/taskforce/admin/site-settings', routes);
+            const req = createMockReq('POST', '/api/taskforce/admin/site-settings', {
+                pricingPageDescription: 'x'.repeat(2001)
+            }, { 'x-taskforce-role': 'admin' });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(400, { 'Content-Type': 'application/json' });
+            expect(res.end.mock.calls[0][0]).toContain('PRICING_PAGE_DESCRIPTION_TOO_LONG');
+            expect(core.updateGlobalSettings).not.toHaveBeenCalled();
+        });
         it('POST /api/taskforce/admin/site_settings should persist website settings for legacy admin bundles', 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.',
+                pricingPageShowPublicDescriptions: false
             }, { '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.',
+                    pricingPageShowPublicDescriptions: false
                 }
             });
         });
@@ -12901,7 +13743,12 @@ 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.',
+                    pricingPageShowPublicDescriptions: false
                 }
             });
             const match = matchRoute('GET', '/api/taskforce/public/site-config', routes);
@@ -12916,7 +13763,12 @@ 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.',
+                    pricingPageShowPublicDescriptions: false
                 }
             });
         });
@@ -12924,7 +13776,12 @@ 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.',
+                    pricingPageShowPublicDescriptions: false
                 }
             });
             const match = matchRoute('GET', '/api/taskforce/public/site-config-script', routes);
@@ -12937,6 +13794,10 @@ 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"');
+            expect(res.end.mock.calls[0][0]).toContain('"pricingPageShowPublicDescriptions":false');
         });
         it('POST /api/taskforce/admin/system-settings should reject invalid onboarding settings', async () => {
             core.validateOnboardingPolicy.mockReturnValueOnce({
@@ -13113,6 +13974,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', {