@taskforcehq/taskforce 0.3.304 → 0.3.306

package/dist/server/routes.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { createRoutes, matchRoute, parseJsonBody } from './routes';
-import { createSessionTokenCookie } from './auth';
+import { createSessionTokenCookie, resolveRequestAccess } from './auth';
 import { TaskforceCore } from '../core/Taskforce';
 import { Readable, Writable } from 'stream';
 import * as fs from 'fs';
@@ -102,6 +102,11 @@ vi.mock('../core/Taskforce', () => {
             });
             listInitiatives = vi.fn().mockReturnValue([]);
             listWorkstreams = vi.fn().mockReturnValue([]);
+            listPlanningBootstrap = vi.fn().mockReturnValue({
+                initiatives: [],
+                workstreams: [],
+                workstreamTaskSummaries: []
+            });
             getInitiativeTemplates = vi.fn();
             createInitiativeFromTemplate = vi.fn();
             getCategories = vi.fn();
@@ -156,6 +161,9 @@ vi.mock('../core/Taskforce', () => {
             listWorkspaceUsers = vi.fn().mockReturnValue([]);
             listAssignableActors = vi.fn();
             listAiProfiles = vi.fn().mockReturnValue([]);
+            countAiProfileUsage = vi.fn().mockReturnValue({ used: 0, limit: null, remaining: null });
+            mergeAiProfiles = vi.fn();
+            archiveAiProfile = vi.fn();
             replaceWorkspaceUsersForSync = vi.fn().mockReturnValue([]);
             listDocumentReviewSessionsForSync = vi.fn().mockReturnValue([]);
             listDocumentReviewCommentsForSync = vi.fn().mockReturnValue([]);
@@ -235,6 +243,7 @@ vi.mock('../core/Taskforce', () => {
                     updatedAt: '2026-01-01T00:00:00.000Z'
                 }
             ]);
+            countSystemUsers = vi.fn().mockReturnValue(1);
             getSystemRole = vi.fn().mockReturnValue('user');
             getUserBetaAccess = vi.fn().mockReturnValue(true);
             setSystemRole = vi.fn().mockReturnValue(true);
@@ -411,7 +420,7 @@ vi.mock('../core/Taskforce', () => {
                     }
                 },
                 {
-                    featureKey: 'workspace.switching',
+                    featureKey: 'workspace.workspaces',
                     label: 'Workspaces',
                     description: 'Allow multiple workspaces with a configurable workspace limit.',
                     allowedAccessModes: ['enabled', 'disabled'],
@@ -624,6 +633,12 @@ describe('Server Routes', () => {
             if (typeof body === 'string') {
                 req.push(body);
             }
+            else if (Buffer.isBuffer(body)) {
+                req.push(body);
+            }
+            else if (body instanceof Uint8Array) {
+                req.push(Buffer.from(body));
+            }
             else {
                 req.push(body ? JSON.stringify(body) : null);
             }
@@ -684,6 +699,33 @@ describe('Server Routes', () => {
             res.__getBody = () => Buffer.concat(bodyChunks).toString('utf8');
             return res;
         };
+        const withDevAuthTokenExposure = async (value, run) => {
+            const previous = process.env.TASKFORCE_AUTH_EXPOSE_DEV_TOKENS;
+            if (value === undefined)
+                delete process.env.TASKFORCE_AUTH_EXPOSE_DEV_TOKENS;
+            else
+                process.env.TASKFORCE_AUTH_EXPOSE_DEV_TOKENS = value;
+            try {
+                await run();
+            }
+            finally {
+                if (previous === undefined)
+                    delete process.env.TASKFORCE_AUTH_EXPOSE_DEV_TOKENS;
+                else
+                    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);
@@ -695,6 +737,30 @@ describe('Server Routes', () => {
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             expect(res.end).toHaveBeenCalledWith(JSON.stringify(mockTasks));
         });
+        it('GET /api/taskforce/planning/bootstrap should return lightweight planning bootstrap data', async () => {
+            const payload = {
+                initiatives: [{ id: 'initiative-1', title: 'Launch', description: null, createdAt: '2026-04-22T00:00:00.000Z' }],
+                workstreams: [{ id: 'workstream-1', title: 'Billing', description: null, createdAt: '2026-04-22T00:00:00.000Z' }],
+                workstreamTaskSummaries: [{
+                        workstreamId: 'workstream-1',
+                        taskCount: 2,
+                        completedTaskCount: 1,
+                        tasks: [
+                            { id: 'task-1', title: 'Draft copy', referenceNumber: 12, status: 'task' },
+                            { id: 'task-2', title: 'Review copy', referenceNumber: 13, status: 'done' }
+                        ]
+                    }]
+            };
+            core.listPlanningBootstrap.mockReturnValue(payload);
+            const match = matchRoute('GET', '/api/taskforce/planning/bootstrap', routes);
+            const req = createMockReq('GET', '/api/taskforce/planning/bootstrap');
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.listPlanningBootstrap).toHaveBeenCalledWith('default', expect.any(Object));
+            expect(res.setHeader).toHaveBeenCalledWith('Server-Timing', expect.stringContaining('planning-bootstrap'));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(JSON.stringify(payload));
+        });
         it('GET /mcp should return MCP JSON error instead of falling through when unauthenticated in cloud runtime', async () => {
             const match = matchRoute('GET', '/mcp', routes);
             const req = createMockReq('GET', '/mcp', undefined, {
@@ -1914,6 +1980,20 @@ describe('Server Routes', () => {
             });
         });
         it('POST /api/taskforce/settings/mcp/test-connection should validate the token against workspace and scopes', async () => {
+            const previousCloudEnvironment = process.env.TASKFORCE_CLOUD_ENVIRONMENT;
+            process.env.TASKFORCE_CLOUD_ENVIRONMENT = 'performance';
+            const fetchMock = vi.fn(async () => new Response(JSON.stringify({
+                jsonrpc: '2.0',
+                id: 'mcp-connection-test',
+                result: {
+                    protocolVersion: '2025-03-26',
+                    serverInfo: { name: 'taskforce-cloud' }
+                }
+            }), {
+                status: 200,
+                headers: { 'Content-Type': 'application/json' }
+            }));
+            vi.stubGlobal('fetch', fetchMock);
             core.inspectMcpAccessToken.mockReturnValue({
                 tokenId: 'mcp-token-1',
                 tokenPrefix: 'tfmcp_abc123',
@@ -1940,12 +2020,136 @@ describe('Server Routes', () => {
             });
             const res = createMockRes();
             res.req = req;
-            await match?.handler(req, res, {});
+            try {
+                await match?.handler(req, res, {});
+            }
+            finally {
+                vi.unstubAllGlobals();
+                if (previousCloudEnvironment === undefined)
+                    delete process.env.TASKFORCE_CLOUD_ENVIRONMENT;
+                else
+                    process.env.TASKFORCE_CLOUD_ENVIRONMENT = previousCloudEnvironment;
+            }
             expect(core.inspectMcpAccessToken).toHaveBeenCalledWith('tfmcp_abc123_secret');
+            expect(fetchMock).toHaveBeenCalledWith('https://performance-mcp.taskforcehq.ai/mcp', expect.objectContaining({
+                method: 'POST',
+                headers: expect.objectContaining({
+                    Authorization: 'Bearer tfmcp_abc123_secret'
+                })
+            }));
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.success).toBe(true);
             expect(payload.result.workspaceName).toBe('Workspace One');
             expect(payload.result.scopes).toEqual(['tasks:read', 'tasks:write']);
+            expect(payload.result.endpoint).toBe('https://performance-mcp.taskforcehq.ai/mcp');
+            expect(payload.result.serverName).toBe('taskforce-cloud');
+            expect(payload.result.protocolVersion).toBe('2025-03-26');
+        });
+        it('POST /api/taskforce/settings/mcp/test-connection should return a clear error when the dedicated MCP host returns a gateway failure', async () => {
+            const previousCloudEnvironment = process.env.TASKFORCE_CLOUD_ENVIRONMENT;
+            process.env.TASKFORCE_CLOUD_ENVIRONMENT = 'performance';
+            const fetchMock = vi.fn(async () => new Response('Bad gateway', {
+                status: 502,
+                headers: { 'Content-Type': 'text/plain' }
+            }));
+            vi.stubGlobal('fetch', fetchMock);
+            core.inspectMcpAccessToken.mockReturnValue({
+                tokenId: 'mcp-token-1',
+                tokenPrefix: 'tfmcp_abc123',
+                workspaceId: 'workspace-1',
+                userId: 'user-1',
+                name: 'Workspace MCP',
+                scopes: ['tasks:read', 'tasks:write'],
+                status: 'active'
+            });
+            const match = matchRoute('POST', '/api/taskforce/settings/mcp/test-connection', routes);
+            const req = createMockReq('POST', '/api/taskforce/settings/mcp/test-connection', {
+                token: 'tfmcp_abc123_secret',
+                requiredScopes: ['tasks:read', 'tasks:write']
+            }, {
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-user-id': 'user-1',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            res.req = req;
+            try {
+                await match?.handler(req, res, {});
+            }
+            finally {
+                vi.unstubAllGlobals();
+                if (previousCloudEnvironment === undefined)
+                    delete process.env.TASKFORCE_CLOUD_ENVIRONMENT;
+                else
+                    process.env.TASKFORCE_CLOUD_ENVIRONMENT = previousCloudEnvironment;
+            }
+            expect(res.writeHead).toHaveBeenCalledWith(502, { 'Content-Type': 'application/json' });
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.success).toBe(false);
+            expect(payload.code).toBe('MCP_ENDPOINT_GATEWAY_ERROR');
+            expect(payload.error).toContain('https://performance-mcp.taskforcehq.ai/mcp');
+            expect(payload.details).toEqual(expect.objectContaining({
+                endpoint: 'https://performance-mcp.taskforcehq.ai/mcp',
+                upstreamStatus: 502
+            }));
+        });
+        it('POST /api/taskforce/settings/mcp/test-connection should prefer the dedicated MCP hostname when cloudMcpBaseUrl points at the app host', async () => {
+            const previousCloudEnvironment = process.env.TASKFORCE_CLOUD_ENVIRONMENT;
+            const previousCloudMcpBaseUrl = process.env.VITE_TASKFORCE_CLOUD_MCP_BASE_URL;
+            process.env.TASKFORCE_CLOUD_ENVIRONMENT = 'performance';
+            process.env.VITE_TASKFORCE_CLOUD_MCP_BASE_URL = 'https://performance-app.taskforcehq.ai';
+            const fetchMock = vi.fn(async () => new Response(JSON.stringify({
+                jsonrpc: '2.0',
+                id: 'mcp-connection-test',
+                result: {
+                    serverInfo: { name: 'taskforce-cloud' }
+                }
+            }), {
+                status: 200,
+                headers: { 'Content-Type': 'application/json' }
+            }));
+            vi.stubGlobal('fetch', fetchMock);
+            core.inspectMcpAccessToken.mockReturnValue({
+                tokenId: 'mcp-token-1',
+                tokenPrefix: 'tfmcp_abc123',
+                workspaceId: 'workspace-1',
+                userId: 'user-1',
+                name: 'Workspace MCP',
+                scopes: ['tasks:read', 'tasks:write'],
+                status: 'active'
+            });
+            core.getWorkspaceProfile.mockReturnValue({
+                id: 'workspace-1',
+                slug: 'workspace-1',
+                name: 'Workspace One',
+                description: null
+            });
+            const match = matchRoute('POST', '/api/taskforce/settings/mcp/test-connection', routes);
+            const req = createMockReq('POST', '/api/taskforce/settings/mcp/test-connection', {
+                token: 'tfmcp_abc123_secret',
+                requiredScopes: ['tasks:read']
+            }, {
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-user-id': 'user-1',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            res.req = req;
+            try {
+                await match?.handler(req, res, {});
+            }
+            finally {
+                vi.unstubAllGlobals();
+                if (previousCloudEnvironment === undefined)
+                    delete process.env.TASKFORCE_CLOUD_ENVIRONMENT;
+                else
+                    process.env.TASKFORCE_CLOUD_ENVIRONMENT = previousCloudEnvironment;
+                if (previousCloudMcpBaseUrl === undefined)
+                    delete process.env.VITE_TASKFORCE_CLOUD_MCP_BASE_URL;
+                else
+                    process.env.VITE_TASKFORCE_CLOUD_MCP_BASE_URL = previousCloudMcpBaseUrl;
+            }
+            expect(fetchMock).toHaveBeenCalledWith('https://performance-mcp.taskforcehq.ai/mcp', expect.any(Object));
         });
         it('POST /api/taskforce/settings/mcp/test-connection should report missing scopes', async () => {
             core.inspectMcpAccessToken.mockReturnValue({
@@ -2003,6 +2207,96 @@ describe('Server Routes', () => {
             expect(fetchMock).not.toHaveBeenCalled();
             vi.unstubAllGlobals();
         });
+        it('GET /api/taskforce/context/:filename should proxy R2 user avatars inline instead of redirecting', async () => {
+            const fetchMock = vi.fn().mockResolvedValue(new Response('avatar-bytes', {
+                status: 200,
+                headers: { 'Content-Type': 'image/webp' }
+            }));
+            vi.stubGlobal('fetch', fetchMock);
+            const routesWithStorage = createRoutes(core, {
+                objectStorage: {
+                    provider: 'r2',
+                    r2: {
+                        accountId: 'acct-1',
+                        bucket: 'taskforce-docs',
+                        endpoint: 'https://example.r2.cloudflarestorage.com',
+                        accessKeyId: 'access-key-1',
+                        secretAccessKey: 'secret-key-1',
+                        keyPrefix: 'taskforce',
+                        signedUploadTtlSeconds: 600,
+                        signedDownloadTtlSeconds: 300
+                    }
+                }
+            });
+            const encoded = encodeURIComponent('users/user-1/profile/avatar/avatar-draft-1-headshot.webp');
+            const match = matchRoute('GET', `/api/taskforce/context/${encoded}`, routesWithStorage);
+            const req = createMockReq('GET', `/api/taskforce/context/${encoded}`);
+            const res = createMockRes();
+            await match?.handler(req, res, { filename: encoded });
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.objectContaining({
+                'Content-Type': 'image/webp',
+                'Content-Disposition': 'inline'
+            }));
+            expect(String(res.getHeader('location') || '')).toBe('');
+            expect(res.__getBody()).toBe('avatar-bytes');
+            expect(String(fetchMock.mock.calls[0][0])).toContain('https://example.r2.cloudflarestorage.com/taskforce-docs/taskforce/users/user-1/profile/avatar/avatar-draft-1-headshot.webp');
+            vi.unstubAllGlobals();
+        });
+        it('GET /api/taskforce/context/:filename should proxy missing cloud-owned user avatars in local runtime', async () => {
+            const previousCloudProxyBaseUrl = process.env.TASKFORCE_CLOUD_PROXY_BASE_URL;
+            const previousClientId = process.env.TASKFORCE_CF_ACCESS_CLIENT_ID;
+            const previousClientSecret = process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET;
+            process.env.TASKFORCE_CLOUD_PROXY_BASE_URL = 'https://performance-app.taskforcehq.ai';
+            process.env.TASKFORCE_CF_ACCESS_CLIENT_ID = 'cf-client-id';
+            process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET = 'cf-client-secret';
+            const fetchMock = vi.fn().mockResolvedValue(new Response('avatar-bytes', {
+                status: 200,
+                headers: {
+                    'Content-Type': 'image/webp',
+                    'Cache-Control': 'private, max-age=60'
+                }
+            }));
+            vi.stubGlobal('fetch', fetchMock);
+            try {
+                const relativePath = 'users/user-1/profile/avatar/avatar-draft-1-headshot.webp';
+                const encoded = encodeURIComponent(relativePath);
+                const match = matchRoute('GET', `/api/taskforce/context/${encoded}`, routes);
+                const req = createMockReq('GET', `/api/taskforce/context/${encoded}`, undefined, {
+                    host: 'localhost:5174',
+                    cookie: 'taskforce_session=session-1',
+                    accept: 'image/webp'
+                });
+                const res = createMockRes();
+                await match?.handler(req, res, { filename: encoded });
+                expect(fetchMock).toHaveBeenCalledWith(`https://performance-app.taskforcehq.ai/api/taskforce/context/${encoded}`, expect.objectContaining({
+                    method: 'GET',
+                    headers: expect.any(Headers)
+                }));
+                const proxiedHeaders = fetchMock.mock.calls[0][1].headers;
+                expect(proxiedHeaders.get('cookie')).toBe('taskforce_session=session-1');
+                expect(proxiedHeaders.get('CF-Access-Client-Id')).toBe('cf-client-id');
+                expect(proxiedHeaders.get('CF-Access-Client-Secret')).toBe('cf-client-secret');
+                expect(res.writeHead).toHaveBeenCalledWith(200, expect.objectContaining({
+                    'content-type': 'image/webp'
+                }));
+                expect(res.__getBody()).toBe('avatar-bytes');
+            }
+            finally {
+                vi.unstubAllGlobals();
+                if (previousCloudProxyBaseUrl === undefined)
+                    delete process.env.TASKFORCE_CLOUD_PROXY_BASE_URL;
+                else
+                    process.env.TASKFORCE_CLOUD_PROXY_BASE_URL = previousCloudProxyBaseUrl;
+                if (previousClientId === undefined)
+                    delete process.env.TASKFORCE_CF_ACCESS_CLIENT_ID;
+                else
+                    process.env.TASKFORCE_CF_ACCESS_CLIENT_ID = previousClientId;
+                if (previousClientSecret === undefined)
+                    delete process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET;
+                else
+                    process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET = previousClientSecret;
+            }
+        });
         it('GET /api/taskforce/context/:filename should proxy inline R2 markdown documents instead of redirecting', async () => {
             const fetchMock = vi.fn().mockResolvedValue({
                 status: 200,
@@ -2230,6 +2524,63 @@ describe('Server Routes', () => {
             expect(fetchMock).not.toHaveBeenCalled();
             vi.unstubAllGlobals();
         });
+        it('GET /api/taskforce/documents/:assetId/content should fall back to object storage when local canonical metadata points at a missing file', async () => {
+            const fetchMock = vi.fn().mockResolvedValue({
+                status: 200,
+                ok: true,
+                headers: new Headers({ 'content-type': 'text/markdown' }),
+                arrayBuffer: async () => Buffer.from('# Recovered canonical doc\n').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 store = new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId());
+            store.upsertAsset({
+                assetId: 'asset-doc-content-fallback-1',
+                workspaceId: 'default',
+                kind: 'document',
+                logicalName: 'Recovered canonical doc',
+                originalFilename: 'recovered-canonical-doc.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'local',
+                storageKey: 'workspaces/default/assets/documents/asset-doc-content-fallback-1-recovered-canonical-doc.md',
+                contentSha256: 'sha-canonical-doc-fallback-1',
+                sizeBytes: 25,
+                documentId: 'doc-content-fallback-1',
+                version: 1,
+                isLatest: true,
+                scanStatus: 'clean',
+                scanEngine: null,
+                scanDetails: null,
+                deletedAt: null,
+                purgeAfter: null
+            });
+            const req = createMockReq('GET', '/api/taskforce/documents/asset-doc-content-fallback-1/content');
+            const res = createMockRes();
+            await matchRoute('GET', '/api/taskforce/documents/asset-doc-content-fallback-1/content', routesWithStorage)?.handler(req, res, {
+                assetId: 'asset-doc-content-fallback-1'
+            });
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.objectContaining({
+                'Content-Type': 'text/markdown',
+                'Content-Disposition': 'inline'
+            }));
+            expect(res.end).toHaveBeenCalledWith(expect.any(Buffer));
+            expect(fetchMock).toHaveBeenCalled();
+            vi.unstubAllGlobals();
+        });
         it('GET /api/taskforce/documents/:assetId/content should reject non-document assets', async () => {
             const routesWithStorage = createRoutes(core, {
                 objectStorage: {
@@ -3236,6 +3587,53 @@ describe('Server Routes', () => {
             fs.rmSync(dbRoot, { recursive: true, force: true });
             fs.rmSync(tmpRoot, { recursive: true, force: true });
         });
+        it('GET /api/taskforce/documents should exclude raw .taskforce/docs markdown files from the document manager', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-exclude-raw-docs-'));
+            const basePath = path.join(tmpRoot, '.taskforce');
+            fs.mkdirSync(path.join(basePath, 'docs'), { recursive: true });
+            fs.writeFileSync(path.join(basePath, 'docs', 'legacy-plan.md'), '# legacy\n', 'utf8');
+            core.getPaths.mockReturnValue({
+                projectRoot: tmpRoot,
+                basePath,
+            });
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            store.upsertAsset({
+                assetId: 'asset-doc-local-2',
+                workspaceId: 'default',
+                kind: 'document',
+                originalFilename: 'managed-plan.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'local',
+                storageKey: 'workspaces/default/assets/documents/asset-doc-local-2-managed-plan.md',
+                contentSha256: 'sha-doc-local-2',
+                sizeBytes: 99,
+                documentId: 'doc-local-2',
+                version: 1,
+                updatedAt: '2026-04-19T12:00:00.000Z'
+            });
+            const routesWithDb = createRoutes(core);
+            const match = matchRoute('GET', '/api/taskforce/documents', routesWithDb);
+            const req = createMockReq('GET', '/api/taskforce/documents', undefined, {
+                'x-taskforce-workspace-id': 'default',
+                'x-taskforce-runtime-mode': 'local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(Array.isArray(payload.documents)).toBe(true);
+            expect(payload.documents).toHaveLength(1);
+            expect(payload.documents[0]).toEqual(expect.objectContaining({
+                id: 'asset-doc-local-2',
+                assetId: 'asset-doc-local-2',
+                fsPath: 'workspaces/default/assets/documents/asset-doc-local-2-managed-plan.md',
+                attachmentState: 'unattached'
+            }));
+            expect(payload.documents.some((doc) => String(doc.fsPath || '').includes('docs/legacy-plan.md'))).toBe(false);
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
         it('GET /api/taskforce/documents should mark canonical docs without links as unattached', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-unattached-local-'));
             core.getPaths.mockReturnValue({
@@ -3332,8 +3730,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'),
@@ -3342,25 +3740,130 @@ 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',
+                workspaceId: 'default',
+                assetId: 'asset-doc-generic-link-1',
+                targetType: 'initiative',
+                targetId: 'initiative-1',
+                role: 'attachment'
+            });
+            const routesWithDb = createRoutes(core);
+            const match = matchRoute('GET', '/api/taskforce/documents', routesWithDb);
+            const req = createMockReq('GET', '/api/taskforce/documents', undefined, {
+                'x-taskforce-workspace-id': 'default',
+                'x-taskforce-runtime-mode': 'local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.documents).toEqual([
+                expect.objectContaining({
+                    id: 'asset-doc-generic-link-1',
+                    assetId: 'asset-doc-generic-link-1',
+                    attachmentCount: 1,
+                    attachmentState: 'attached',
+                    taskId: null
+                })
+            ]);
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
+        it('POST /api/taskforce/documents/:assetId/attach should attach a canonical document to a task target', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-attach-task-'));
+            core.getPaths.mockReturnValue({
+                projectRoot: tmpRoot,
+                basePath: path.join(tmpRoot, '.taskforce'),
+            });
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            store.upsertAsset({
+                assetId: 'asset-doc-attach-route-1',
+                workspaceId: 'default',
+                kind: 'document',
+                logicalName: 'Attach Me',
+                originalFilename: 'attach-me.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'local',
+                storageKey: 'workspaces/default/assets/documents/asset-doc-attach-route-1-attach-me.md',
+                contentSha256: 'sha-doc-attach-route-1',
+                sizeBytes: 28,
+                documentId: 'doc-attach-route-1',
+                version: 1,
+                updatedAt: '2026-03-18T13:30:00.000Z'
+            });
+            core.getTask.mockImplementation((id) => id === 'task-attach-1'
+                ? { id: 'task-attach-1', title: 'Attach target', attachments: [] }
+                : null);
+            const routesWithDb = createRoutes(core);
+            const match = matchRoute('POST', '/api/taskforce/documents/asset-doc-attach-route-1/attach', routesWithDb);
+            const req = createMockReq('POST', '/api/taskforce/documents/asset-doc-attach-route-1/attach', {
+                targetType: 'task',
+                targetId: 'task-attach-1',
+            }, {
+                'x-taskforce-workspace-id': 'default'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { assetId: 'asset-doc-attach-route-1' });
+            expect(res.writeHead).toHaveBeenCalledWith(200, { 'Content-Type': 'application/json' });
+            expect(core.updateTask).toHaveBeenCalledWith('task-attach-1', expect.objectContaining({
+                attachments: [
+                    expect.objectContaining({
+                        assetId: 'asset-doc-attach-route-1',
+                        taskId: 'task-attach-1',
+                        path: '/api/taskforce/documents/asset-doc-attach-route-1/content',
+                    })
+                ]
+            }), 'default', expect.objectContaining({
+                actorRef: 'user',
+                saveSource: 'manual',
+            }));
+            expect(core.notifyDocumentMetadataMutation).toHaveBeenCalledWith('default', ['workspaces/default/assets/documents/asset-doc-attach-route-1-attach-me.md'], 'upsert');
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
+        it('GET /api/taskforce/documents should normalize readable names and attachment metadata for sparse canonical assets', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-normalized-cloud-'));
+            core.getPaths.mockReturnValue({
+                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'
@@ -3485,10 +3988,106 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, { assetId: 'asset-doc-attached-1' });
             expect(res.writeHead).toHaveBeenCalledWith(409, { 'Content-Type': 'application/json' });
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload).toEqual(expect.objectContaining({
+                error: 'Document is still attached to one or more tasks.',
+                activeAttachmentCount: 1,
+                requiresForceDetach: true
+            }));
             expect(store.get('asset-doc-attached-1', 'default')?.deletedAt).toBeNull();
             fs.rmSync(dbRoot, { recursive: true, force: true });
             fs.rmSync(tmpRoot, { recursive: true, force: true });
         });
+        it('DELETE /api/taskforce/documents/:assetId should unlink attached canonical documents when forceDetach is true', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-delete-force-attached-'));
+            const basePath = path.join(tmpRoot, '.taskforce');
+            const documentPath = path.join(basePath, 'workspaces', 'default', 'assets', 'documents', 'asset-doc-force-delete-1-notes.md');
+            fs.mkdirSync(path.dirname(documentPath), { recursive: true });
+            fs.writeFileSync(documentPath, '# attached\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-force-delete-1',
+                workspaceId: 'default',
+                kind: 'document',
+                originalFilename: 'notes.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'local',
+                storageKey: 'workspaces/default/assets/documents/asset-doc-force-delete-1-notes.md',
+                contentSha256: 'sha-doc-force-delete-1',
+                sizeBytes: 16,
+                documentId: 'doc-force-delete-1',
+                version: 1,
+                updatedAt: '2026-03-18T14:00:00.000Z'
+            });
+            store.upsertLink({
+                workspaceId: 'default',
+                assetId: 'asset-doc-force-delete-1',
+                taskId: 'task-keep',
+                role: 'attachment'
+            });
+            core.getTask.mockImplementation((id) => id === 'task-keep'
+                ? {
+                    id: 'task-keep',
+                    title: 'Task Keep',
+                    attachments: [{
+                            path: '/api/taskforce/documents/asset-doc-force-delete-1/content',
+                            fsPath: 'workspaces/default/assets/documents/asset-doc-force-delete-1-notes.md',
+                            caption: 'notes.md',
+                            assetId: 'asset-doc-force-delete-1'
+                        }, {
+                            path: '/api/taskforce/context/other-file.md',
+                            fsPath: 'workspaces/default/assets/files/other-file.md',
+                            caption: 'other-file.md'
+                        }]
+                }
+                : null);
+            core.updateTask.mockImplementation((_id, patch) => ({
+                id: 'task-keep',
+                attachments: patch.attachments
+            }));
+            const routesWithDb = createRoutes(core);
+            const match = matchRoute('DELETE', '/api/taskforce/documents/asset-doc-force-delete-1', routesWithDb);
+            const req = createMockReq('DELETE', '/api/taskforce/documents/asset-doc-force-delete-1', {
+                forceDetach: true
+            }, {
+                'x-taskforce-workspace-id': 'default'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { assetId: 'asset-doc-force-delete-1' });
+            expect(core.updateTask).toHaveBeenCalledWith('task-keep', {
+                attachments: [{
+                        path: '/api/taskforce/context/other-file.md',
+                        fsPath: 'workspaces/default/assets/files/other-file.md',
+                        caption: 'other-file.md'
+                    }]
+            }, 'default', expect.objectContaining({ actorRef: 'user', saveSource: 'manual' }));
+            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,
+                softDeleted: true,
+                detachedTaskCount: 1
+            }));
+            expect(store.get('asset-doc-force-delete-1', 'default')).toEqual(expect.objectContaining({
+                deletedAt: expect.any(String),
+                purgeAfter: expect.any(String)
+            }));
+            expect(store.listLinksForAsset('asset-doc-force-delete-1', 'default', { includeDeleted: true })).toEqual([
+                expect.objectContaining({
+                    taskId: 'task-keep',
+                    role: 'attachment',
+                    deletedAt: expect.any(String)
+                })
+            ]);
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
         it('PATCH /api/taskforce/documents/:assetId should update the shared display name without changing storage identity', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-documents-rename-'));
             core.getPaths.mockReturnValue({
@@ -3726,7 +4325,85 @@ describe('Server Routes', () => {
             }));
             expect(res.setHeader).not.toHaveBeenCalledWith('Set-Cookie', expect.any(String));
             expect(res.writeHead).toHaveBeenCalledWith(201, expect.any(Object));
-            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"verificationRequired":true'));
+            const payload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+            expect(payload).toEqual(expect.objectContaining({
+                success: true,
+                verificationRequired: true
+            }));
+            expect(payload.verificationToken).toBeUndefined();
+        });
+        it('POST /api/taskforce/auth/register should not depend on onboarding policy lookups', 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
+            };
+            core.getOnboardingPolicy.mockImplementationOnce(() => {
+                throw new Error('for SELECT DISTINCT, ORDER BY expressions must appear in select list');
+            });
+            core.getGlobalSettings.mockReturnValue({
+                auth: {
+                    allowSelfRegistration: true,
+                    requireVerifiedEmail: false
+                }
+            });
+            routes = createRoutes(core, { authConfig });
+            core.registerPasswordUser.mockReturnValueOnce({
+                userId: 'u-new',
+                workspaceId: 'default',
+                role: 'member',
+                planSelectionRequired: false
+            });
+            const match = matchRoute('POST', '/api/taskforce/auth/register', routes);
+            const req = createMockReq('POST', '/api/taskforce/auth/register', {
+                email: 'newuser@example.com',
+                password: 'password123'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.registerPasswordUser).toHaveBeenCalledWith(expect.objectContaining({
+                email: 'newuser@example.com'
+            }));
+            expect(res.writeHead).toHaveBeenCalledWith(201, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
+        });
+        it('POST /api/taskforce/auth/register should only expose verificationToken when explicitly enabled', 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
+            };
+            await withDevAuthTokenExposure('true', async () => {
+                routes = createRoutes(core, { authConfig });
+                core.registerPasswordUser.mockReturnValueOnce({
+                    userId: 'user-opt-in',
+                    workspaceId: null,
+                    role: 'member',
+                    planSelectionRequired: false
+                });
+                core.requestEmailVerification.mockReturnValueOnce({ token: 'verify-token-opt-in' });
+                const match = matchRoute('POST', '/api/taskforce/auth/register', routes);
+                const req = createMockReq('POST', '/api/taskforce/auth/register', {
+                    email: 'opt-in@example.com',
+                    password: 'password123'
+                });
+                const res = createMockRes();
+                await match?.handler(req, res, {});
+                const payload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+                expect(payload.verificationToken).toBe('verify-token-opt-in');
+            });
         });
         it('POST /api/taskforce/auth/register should allow first-time registration without workspaceId', async () => {
             const authConfig = {
@@ -3851,35 +4528,37 @@ describe('Server Routes', () => {
                 sessionSecret: 'test-secret',
                 sessionTtlSeconds: 3600
             };
-            routes = createRoutes(core, { authConfig });
-            core.hasWorkspaceAdmin.mockReturnValueOnce(true);
-            core.isEmailVerified.mockReturnValueOnce(false);
-            core.requestEmailVerification.mockReturnValueOnce({ token: 'verify-token-existing' });
-            const error = new Error('Email is already registered');
-            error.statusCode = 409;
-            error.code = 'EMAIL_ALREADY_EXISTS';
-            core.registerPasswordUser.mockImplementationOnce(() => {
-                throw error;
-            });
-            const match = matchRoute('POST', '/api/taskforce/auth/register', routes);
-            const req = createMockReq('POST', '/api/taskforce/auth/register', {
-                email: 'owner@example.com',
-                password: 'password123',
-                workspaceId: 'workspace-1'
+            await withDevAuthTokenExposure('true', async () => {
+                routes = createRoutes(core, { authConfig });
+                core.hasWorkspaceAdmin.mockReturnValueOnce(true);
+                core.isEmailVerified.mockReturnValueOnce(false);
+                core.requestEmailVerification.mockReturnValueOnce({ token: 'verify-token-existing' });
+                const error = new Error('Email is already registered');
+                error.statusCode = 409;
+                error.code = 'EMAIL_ALREADY_EXISTS';
+                core.registerPasswordUser.mockImplementationOnce(() => {
+                    throw error;
+                });
+                const match = matchRoute('POST', '/api/taskforce/auth/register', routes);
+                const req = createMockReq('POST', '/api/taskforce/auth/register', {
+                    email: 'owner@example.com',
+                    password: 'password123',
+                    workspaceId: 'workspace-1'
+                });
+                const res = createMockRes();
+                await match?.handler(req, res, {});
+                expect(core.isEmailVerified).toHaveBeenCalledWith('owner@example.com');
+                expect(core.requestEmailVerification).toHaveBeenCalledWith({ email: 'owner@example.com' });
+                expect(res.writeHead).toHaveBeenCalledWith(409, expect.any(Object));
+                const responsePayload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+                expect(responsePayload).toEqual(expect.objectContaining({
+                    success: false,
+                    code: 'EMAIL_ALREADY_EXISTS_UNVERIFIED',
+                    verificationRequired: true,
+                    emailSent: true,
+                    verificationToken: 'verify-token-existing'
+                }));
             });
-            const res = createMockRes();
-            await match?.handler(req, res, {});
-            expect(core.isEmailVerified).toHaveBeenCalledWith('owner@example.com');
-            expect(core.requestEmailVerification).toHaveBeenCalledWith({ email: 'owner@example.com' });
-            expect(res.writeHead).toHaveBeenCalledWith(409, expect.any(Object));
-            const responsePayload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
-            expect(responsePayload).toEqual(expect.objectContaining({
-                success: false,
-                code: 'EMAIL_ALREADY_EXISTS_UNVERIFIED',
-                verificationRequired: true,
-                emailSent: true,
-                verificationToken: 'verify-token-existing'
-            }));
         });
         it('POST /api/taskforce/auth/register should return conflict when verified email exists', async () => {
             const authConfig = {
@@ -3952,6 +4631,124 @@ describe('Server Routes', () => {
                 code: 'SIGNUP_PLAN_VERSION_NOT_FOUND'
             }));
         });
+        it('POST /api/taskforce/auth/verify-email/request should report no-send cases without claiming delivery', 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.requestEmailVerification.mockReturnValueOnce({});
+            const match = matchRoute('POST', '/api/taskforce/auth/verify-email/request', routes);
+            const req = createMockReq('POST', '/api/taskforce/auth/verify-email/request', { email: 'nobody@example.com' });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+            expect(payload).toMatchObject({
+                success: true,
+                emailSent: false,
+                deliveryAttempted: false
+            });
+            expect(payload.emailError).toBeUndefined();
+        });
+        it('POST /api/taskforce/auth/verify-email/request should only expose verificationToken when explicitly enabled', 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
+            };
+            await withDevAuthTokenExposure(undefined, async () => {
+                routes = createRoutes(core, { authConfig });
+                core.requestEmailVerification.mockReturnValueOnce({ token: 'verify-token-hidden' });
+                const match = matchRoute('POST', '/api/taskforce/auth/verify-email/request', routes);
+                const req = createMockReq('POST', '/api/taskforce/auth/verify-email/request', { email: 'owner@example.com' });
+                const res = createMockRes();
+                await match?.handler(req, res, {});
+                const payload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+                expect(payload.verificationToken).toBeUndefined();
+            });
+            await withDevAuthTokenExposure('true', async () => {
+                routes = createRoutes(core, { authConfig });
+                core.requestEmailVerification.mockReturnValueOnce({ token: 'verify-token-visible' });
+                const match = matchRoute('POST', '/api/taskforce/auth/verify-email/request', routes);
+                const req = createMockReq('POST', '/api/taskforce/auth/verify-email/request', { email: 'owner@example.com' });
+                const res = createMockRes();
+                await match?.handler(req, res, {});
+                const payload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+                expect(payload.verificationToken).toBe('verify-token-visible');
+            });
+        });
+        it('POST /api/taskforce/auth/password-reset/request should report no-send cases without claiming delivery', 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.requestPasswordReset.mockReturnValueOnce({});
+            const match = matchRoute('POST', '/api/taskforce/auth/password-reset/request', routes);
+            const req = createMockReq('POST', '/api/taskforce/auth/password-reset/request', { email: 'nobody@example.com' });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+            expect(payload).toMatchObject({
+                success: true,
+                emailSent: false,
+                deliveryAttempted: false
+            });
+            expect(payload.emailError).toBeUndefined();
+        });
+        it('POST /api/taskforce/auth/password-reset/request should only expose resetToken when explicitly enabled', 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
+            };
+            await withDevAuthTokenExposure(undefined, async () => {
+                routes = createRoutes(core, { authConfig });
+                core.requestPasswordReset.mockReturnValueOnce({ token: 'reset-token-hidden' });
+                const match = matchRoute('POST', '/api/taskforce/auth/password-reset/request', routes);
+                const req = createMockReq('POST', '/api/taskforce/auth/password-reset/request', { email: 'owner@example.com' });
+                const res = createMockRes();
+                await match?.handler(req, res, {});
+                const payload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+                expect(payload.resetToken).toBeUndefined();
+            });
+            await withDevAuthTokenExposure('true', async () => {
+                routes = createRoutes(core, { authConfig });
+                core.requestPasswordReset.mockReturnValueOnce({ token: 'reset-token-visible' });
+                const match = matchRoute('POST', '/api/taskforce/auth/password-reset/request', routes);
+                const req = createMockReq('POST', '/api/taskforce/auth/password-reset/request', { email: 'owner@example.com' });
+                const res = createMockRes();
+                await match?.handler(req, res, {});
+                const payload = JSON.parse(String(res.end.mock.calls.at(-1)?.[0] || '{}'));
+                expect(payload.resetToken).toBe('reset-token-visible');
+            });
+        });
         it('POST /api/taskforce/auth/verify-email/confirm should verify token', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -4054,6 +4851,40 @@ describe('Server Routes', () => {
             expect(payload.inviteeKind).toBe('existing_user');
             expect(payload.passwordRequired).toBe(false);
         });
+        it('POST /api/taskforce/auth/invite/accept should preserve the created identity in the session cookie', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.acceptInviteWithToken.mockReturnValueOnce({
+                userId: 'u1',
+                email: 'u1@example.com',
+                workspaceId: 'workspace-1',
+                role: 'member',
+                identityId: 'identity-password-u1'
+            });
+            const match = matchRoute('POST', '/api/taskforce/auth/invite/accept', routes);
+            const req = createMockReq('POST', '/api/taskforce/auth/invite/accept', { token: 'accept-token', password: 'password123' }, {
+                'x-taskforce-runtime-mode': 'cloud',
+                host: 'localhost'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const setCookie = res.setHeader.mock.calls.find(([name]) => name === 'Set-Cookie')?.[1];
+            expect(typeof setCookie).toBe('string');
+            const cookieReq = createMockReq('GET', '/api/taskforce/me', undefined, { cookie: setCookie });
+            const access = resolveRequestAccess(cookieReq, authConfig);
+            expect(access.identityId).toBe('identity-password-u1');
+            expect(access.userId).toBe('u1');
+        });
         it('POST /api/taskforce/auth/invite/accept should return expired code and audit action', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -4144,7 +4975,8 @@ describe('Server Routes', () => {
             const cookie = createSessionTokenCookie('session-join', authConfig, {
                 userId: 'u1',
                 role: 'member',
-                workspaceId: 'workspace-1'
+                workspaceId: 'workspace-1',
+                identityId: 'identity-u1'
             });
             const match = matchRoute('POST', '/api/taskforce/auth/invite/join', routes);
             const req = createMockReq('POST', '/api/taskforce/auth/invite/join', { token: 'join-token' }, {
@@ -4158,6 +4990,11 @@ describe('Server Routes', () => {
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.workspaceId).toBe('workspace-1');
+            const setCookie = res.setHeader.mock.calls.find(([name]) => name === 'Set-Cookie')?.[1];
+            expect(typeof setCookie).toBe('string');
+            const cookieReq = createMockReq('GET', '/api/taskforce/me', undefined, { cookie: setCookie });
+            const access = resolveRequestAccess(cookieReq, authConfig);
+            expect(access.identityId).toBe('identity-u1');
         });
         it('POST /api/taskforce/auth/login should auto-verify bootstrap admin and sign in', async () => {
             const authConfig = {
@@ -4390,22 +5227,56 @@ describe('Server Routes', () => {
             };
             routes = createRoutes(core, { authConfig });
             core.authenticatePasswordUserDetailed.mockReturnValueOnce({
-                ok: true,
-                access: { userId: 'u4', workspaceId: 'default', role: 'member' }
+                ok: true,
+                access: { userId: 'u4', workspaceId: 'default', role: 'member' }
+            });
+            const match = matchRoute('POST', '/api/taskforce/auth/login', routes);
+            const req = createMockReq('POST', '/api/taskforce/auth/login', {
+                email: 'returning@example.com',
+                password: 'password123'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.authenticatePasswordUserDetailed).toHaveBeenCalledWith(expect.objectContaining({
+                email: 'returning@example.com',
+                workspaceId: 'default'
+            }));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
+        });
+        it('POST /api/taskforce/auth/login should not depend on onboarding policy lookups', 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
+            };
+            core.getOnboardingPolicy.mockImplementationOnce(() => {
+                throw new Error('for SELECT DISTINCT, ORDER BY expressions must appear in select list');
+            });
+            routes = createRoutes(core, { authConfig });
+            core.authenticatePasswordUserDetailed.mockReturnValueOnce({
+                ok: false,
+                code: 'INVALID_CREDENTIALS'
             });
             const match = matchRoute('POST', '/api/taskforce/auth/login', routes);
             const req = createMockReq('POST', '/api/taskforce/auth/login', {
-                email: 'returning@example.com',
-                password: 'password123'
+                email: 'user@example.com',
+                password: 'wrongpass'
             });
             const res = createMockRes();
             await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(401, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('Invalid email/password.'));
             expect(core.authenticatePasswordUserDetailed).toHaveBeenCalledWith(expect.objectContaining({
-                email: 'returning@example.com',
-                workspaceId: 'default'
+                email: 'user@example.com',
+                requireVerifiedEmail: true
             }));
-            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
-            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
         });
         it('GET /api/taskforce/workspaces should list authenticated user workspaces', async () => {
             const authConfig = {
@@ -4452,6 +5323,7 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.listUserWorkspaces).toHaveBeenCalledWith('user-1');
+            expect(res.setHeader).toHaveBeenCalledWith('Server-Timing', expect.stringContaining('workspaces'));
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"workspace-2"'));
         });
@@ -5345,6 +6217,9 @@ describe('Server Routes', () => {
             await match?.handler(req, res, {});
             const payloadRaw = res.end.mock.calls[0]?.[0];
             const payload = JSON.parse(String(payloadRaw || '{}'));
+            expect(payload.knownPaths).toEqual([
+                'workspaces/workspace-local/assets/documents/asset-doc-snapshot-1-sync-notes.md'
+            ]);
             expect(payload.documents).toEqual(expect.arrayContaining([
                 expect.objectContaining({
                     path: 'workspaces/workspace-local/assets/documents/asset-doc-snapshot-1-sync-notes.md',
@@ -5359,7 +6234,56 @@ describe('Server Routes', () => {
             expect(String(payload.fingerprint || '')).toContain('asset-doc-snapshot-1');
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
-        it('GET /api/taskforce/sync/workspace/documents should include docs folder markdown files without canonical asset metadata', async () => {
+        it('GET /api/taskforce/sync/workspace/documents should retain canonical knownPaths even when content is temporarily unreadable', async () => {
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-documents-known-paths-'));
+            const projectRoot = fs.realpathSync(tmpRoot);
+            const basePath = path.join(tmpRoot, '.taskforce');
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            store.upsertAsset({
+                assetId: 'asset-doc-known-path-1',
+                workspaceId: 'workspace-local',
+                kind: 'document',
+                originalFilename: 'missing-content.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'local',
+                storageKey: 'workspaces/workspace-local/assets/documents/asset-doc-known-path-1-missing-content.md',
+                contentSha256: 'missing-content-hash',
+                sizeBytes: 17,
+                documentId: 'doc-known-path-1',
+                version: 1,
+                isLatest: true,
+                createdAt: '2026-03-17T09:00:00.000Z',
+                updatedAt: '2026-03-17T10:00:00.000Z'
+            });
+            store.upsertLink({
+                workspaceId: 'workspace-local',
+                assetId: 'asset-doc-known-path-1',
+                taskId: 'task-1',
+                role: 'attachment'
+            });
+            core.getPaths.mockReturnValue({
+                projectRoot,
+                basePath,
+            });
+            core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            const match = matchRoute('GET', '/api/taskforce/sync/workspace/documents', routes);
+            const req = createMockReq('GET', '/api/taskforce/sync/workspace/documents?workspaceId=workspace-local', undefined, {
+                'x-taskforce-workspace-id': 'workspace-local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payloadRaw = res.end.mock.calls[0]?.[0];
+            const payload = JSON.parse(String(payloadRaw || '{}'));
+            expect(payload.documents).toEqual([]);
+            expect(payload.knownPaths).toEqual([
+                'workspaces/workspace-local/assets/documents/asset-doc-known-path-1-missing-content.md'
+            ]);
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+        });
+        it('GET /api/taskforce/sync/workspace/documents should exclude docs folder markdown files that are not canonical assets', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-documents-legacy-ignore-'));
             const projectRoot = fs.realpathSync(tmpRoot);
             const basePath = path.join(tmpRoot, '.taskforce');
@@ -5384,12 +6308,7 @@ describe('Server Routes', () => {
             const payloadRaw = res.end.mock.calls[0]?.[0];
             const payload = JSON.parse(String(payloadRaw || '{}'));
             expect(Array.isArray(payload.documents)).toBe(true);
-            expect(payload.documents).toEqual([
-                expect.objectContaining({
-                    path: 'docs/legacy-notes.md',
-                    content: '# legacy\n'
-                })
-            ]);
+            expect(payload.documents).toEqual([]);
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
         it('GET /api/taskforce/sync/workspace/document-reviews should include document review sessions for the requested workspace', async () => {
@@ -5726,6 +6645,109 @@ describe('Server Routes', () => {
             ]));
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
+        it('GET /api/taskforce/sync/workspace/pull should hydrate canonical markdown documents from 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({
+                status: 200,
+                ok: true,
+                headers: new Headers({ 'content-type': 'text/markdown' }),
+                arrayBuffer: async () => Uint8Array.from(Buffer.from('# Canonical R2 doc\n')).buffer,
+            });
+            vi.stubGlobal('fetch', fetchMock);
+            const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-pull-doc-r2-'));
+            const basePath = path.join(tmpRoot, '.taskforce');
+            fs.mkdirSync(basePath, { recursive: true });
+            const { tmpRoot: dbRoot, db, store } = createWorkspaceAssetTestStore();
+            store.upsertAsset({
+                assetId: 'asset-doc-r2-1',
+                workspaceId: 'workspace-1',
+                kind: 'document',
+                originalFilename: 'canonical-r2-doc.md',
+                mimeType: 'text/markdown',
+                storageProvider: 'r2',
+                storageKey: 'workspaces/workspace-1/assets/documents/asset-doc-r2-1-canonical-r2-doc.md',
+                contentSha256: 'sha-doc-r2-1',
+                sizeBytes: 19,
+                documentId: 'doc-r2-1',
+                referenceNumber: 201,
+                version: 2,
+                isLatest: true,
+                createdAt: '2026-03-17T09:00:00.000Z',
+                updatedAt: '2026-03-17T10:00:00.000Z'
+            });
+            store.upsertLink({
+                workspaceId: 'workspace-1',
+                assetId: 'asset-doc-r2-1',
+                taskId: 'task-1',
+                role: 'attachment',
+                createdAt: '2026-03-17T10:00:00.000Z',
+                updatedAt: '2026-03-17T10:00:00.000Z'
+            });
+            core.getPaths.mockReturnValue({
+                projectRoot: tmpRoot,
+                basePath,
+            });
+            core.getDatabaseAdapter = vi.fn().mockReturnValue(db);
+            core.getTenantId = vi.fn().mockReturnValue('default');
+            routes = 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.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-doc-r2', 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 payloadRaw = res.end.mock.calls[0]?.[0];
+            const payload = JSON.parse(String(payloadRaw || '{}'));
+            expect(payload.changes).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    op: 'document-upsert',
+                    path: 'workspaces/workspace-1/assets/documents/asset-doc-r2-1-canonical-r2-doc.md',
+                    content: '# Canonical R2 doc\n',
+                    assetId: 'asset-doc-r2-1',
+                    documentId: 'doc-r2-1',
+                    referenceNumber: 201,
+                    version: 2,
+                    taskId: 'task-1',
+                    originalFilename: 'canonical-r2-doc.md',
+                    linkRole: 'attachment'
+                })
+            ]));
+            expect(fetchMock).toHaveBeenCalled();
+            vi.unstubAllGlobals();
+            fs.rmSync(dbRoot, { recursive: true, force: true });
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        });
         it('GET /api/taskforce/sync/workspace/pull should include document review session upserts and deletes', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -6376,29 +7398,144 @@ describe('Server Routes', () => {
                 workspaceId: 'workspace-cloud-selected',
                 userId: 'user-1'
             });
-            core.listUserWorkspaces.mockReturnValueOnce([
-                {
-                    id: 'workspace-local-active',
-                    slug: 'workspace-local-active',
-                    name: 'Workspace Local Active',
-                    description: null,
-                    role: 'owner',
-                    status: 'active',
-                    betaAccess: true
-                }
-            ]);
-            core.listTasks.mockReturnValueOnce({ tasks: [] });
-            core.listArchive.mockReturnValueOnce({ archived: [] });
+            core.listUserWorkspaces.mockReturnValueOnce([
+                {
+                    id: 'workspace-local-active',
+                    slug: 'workspace-local-active',
+                    name: 'Workspace Local Active',
+                    description: null,
+                    role: 'owner',
+                    status: 'active',
+                    betaAccess: true
+                }
+            ]);
+            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?limit=10&workspaceId=workspace-local-active', undefined, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.listUserWorkspaces).toHaveBeenCalledWith('user-1');
+            expect(core.listTasks).toHaveBeenCalledWith('workspace-local-active');
+            expect(core.listArchive).toHaveBeenCalledWith('workspace-local-active');
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        });
+        it('GET /api/taskforce/sync/workspace/pull should maintain stable cursor pagination for equal watermarks', 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-pull-cursor-contract', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-1',
+                userId: 'user-1'
+            });
+            core.listTasks.mockReturnValue({
+                tasks: [
+                    { id: 'task-b', title: 'Task B', createdAt: '2026-02-19T16:00:00.000Z', updatedAt: '2026-02-19T16:10:00.000Z' },
+                    { id: 'task-a', title: 'Task A', createdAt: '2026-02-19T16:00:00.000Z', updatedAt: '2026-02-19T16:10:00.000Z' },
+                    { id: 'task-c', title: 'Task C', createdAt: '2026-02-19T16:00:00.000Z', updatedAt: '2026-02-19T16:11:00.000Z' }
+                ]
+            });
+            core.listArchive.mockReturnValue({ archived: [] });
+            const match = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
+            const firstReq = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-1&limit=1', undefined, { cookie });
+            const firstRes = createMockRes();
+            await match?.handler(firstReq, firstRes, {});
+            const firstBody = JSON.parse(String(firstRes.end.mock.calls[0]?.[0] || '{}'));
+            expect(firstBody?.changes?.[0]).toEqual(expect.objectContaining({
+                op: 'upsert',
+                task: expect.objectContaining({ id: 'task-a' })
+            }));
+            expect(typeof firstBody?.nextCursor).toBe('string');
+            const secondReq = createMockReq('GET', `/api/taskforce/sync/workspace/pull?workspaceId=workspace-1&limit=1&cursor=${encodeURIComponent(String(firstBody.nextCursor || ''))}`, undefined, { cookie });
+            const secondRes = createMockRes();
+            await match?.handler(secondReq, secondRes, {});
+            const secondBody = JSON.parse(String(secondRes.end.mock.calls[0]?.[0] || '{}'));
+            expect(secondBody?.changes?.[0]).toEqual(expect.objectContaining({
+                op: 'upsert',
+                task: expect.objectContaining({ id: 'task-b' })
+            }));
+        });
+        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,
+                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-pull-invalid-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', 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?limit=10&workspaceId=workspace-local-active', undefined, { cookie });
+            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(core.listUserWorkspaces).toHaveBeenCalledWith('user-1');
-            expect(core.listTasks).toHaveBeenCalledWith('workspace-local-active');
-            expect(core.listArchive).toHaveBeenCalledWith('workspace-local-active');
             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 maintain stable cursor pagination for equal watermarks', async () => {
+        it('GET /api/taskforce/sync/workspace/pull should still return success when success audit throws', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
                 enabled: true,
@@ -6411,38 +7548,27 @@ describe('Server Routes', () => {
                 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-pull-cursor-contract', 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'
             });
-            core.listTasks.mockReturnValue({
-                tasks: [
-                    { id: 'task-b', title: 'Task B', createdAt: '2026-02-19T16:00:00.000Z', updatedAt: '2026-02-19T16:10:00.000Z' },
-                    { id: 'task-a', title: 'Task A', createdAt: '2026-02-19T16:00:00.000Z', updatedAt: '2026-02-19T16:10:00.000Z' },
-                    { id: 'task-c', title: 'Task C', createdAt: '2026-02-19T16:00:00.000Z', updatedAt: '2026-02-19T16:11:00.000Z' }
-                ]
+            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;
             });
-            core.listArchive.mockReturnValue({ archived: [] });
             const match = matchRoute('GET', '/api/taskforce/sync/workspace/pull', routes);
-            const firstReq = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-1&limit=1', undefined, { cookie });
-            const firstRes = createMockRes();
-            await match?.handler(firstReq, firstRes, {});
-            const firstBody = JSON.parse(String(firstRes.end.mock.calls[0]?.[0] || '{}'));
-            expect(firstBody?.changes?.[0]).toEqual(expect.objectContaining({
-                op: 'upsert',
-                task: expect.objectContaining({ id: 'task-a' })
-            }));
-            expect(typeof firstBody?.nextCursor).toBe('string');
-            const secondReq = createMockReq('GET', `/api/taskforce/sync/workspace/pull?workspaceId=workspace-1&limit=1&cursor=${encodeURIComponent(String(firstBody.nextCursor || ''))}`, undefined, { cookie });
-            const secondRes = createMockRes();
-            await match?.handler(secondReq, secondRes, {});
-            const secondBody = JSON.parse(String(secondRes.end.mock.calls[0]?.[0] || '{}'));
-            expect(secondBody?.changes?.[0]).toEqual(expect.objectContaining({
-                op: 'upsert',
-                task: expect.objectContaining({ id: 'task-b' })
-            }));
+            const req = createMockReq('GET', '/api/taskforce/sync/workspace/pull?workspaceId=workspace-1&limit=10', undefined, { cookie });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledTimes(1);
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
         });
         it('GET /api/taskforce/sync/workspace/pull should reject unauthorized workspace override', async () => {
             const authConfig = {
@@ -6505,6 +7631,53 @@ describe('Server Routes', () => {
             }), 'workspace-local');
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
+        it('POST /api/taskforce/sync/workspace/apply-local should still return success when success sync telemetry throws after apply', async () => {
+            core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
+            routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            core.recordSyncEvent.mockImplementationOnce(() => {
+                throw new Error('telemetry unavailable');
+            });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+            const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+                changes: [
+                    { op: 'upsert', archived: false, task: { id: 'task-1', title: 'Task 1' } }
+                ]
+            }, {
+                'x-taskforce-workspace-id': 'workspace-local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledTimes(1);
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
+        });
+        it('POST /api/taskforce/sync/workspace/apply-local should still return error response when failure-path telemetry throws', async () => {
+            core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
+            routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
+            core.applyWorkspaceSyncSnapshot.mockImplementationOnce(() => {
+                throw new Error('apply failed');
+            });
+            core.recordSyncEvent.mockImplementationOnce(() => {
+                throw new Error('telemetry unavailable');
+            });
+            const match = matchRoute('POST', '/api/taskforce/sync/workspace/apply-local', routes);
+            const req = createMockReq('POST', '/api/taskforce/sync/workspace/apply-local', {
+                changes: [
+                    { op: 'upsert', archived: false, task: { id: 'task-1', title: 'Task 1' } }
+                ]
+            }, {
+                'x-taskforce-workspace-id': 'workspace-local'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledTimes(1);
+            expect(res.writeHead).toHaveBeenCalledWith(400, expect.any(Object));
+            expect(res.end).toHaveBeenCalledTimes(1);
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":false'));
+        });
         it('POST /api/taskforce/sync/workspace/apply-local should apply document review session upserts and deletes', async () => {
             core.resolvePreferredWorkspaceId.mockReturnValue('workspace-local');
             routes = createRoutes(core, { authConfig: { runtimeMode: 'local', enabled: false } });
@@ -7249,7 +8422,7 @@ describe('Server Routes', () => {
             ]);
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
-        it('POST /api/taskforce/sync/workspace/apply-local should preserve document references during normal sync when content is unchanged', async () => {
+        it('POST /api/taskforce/sync/workspace/apply-local should adopt cloud document references during normal sync even when content is unchanged', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-apply-doc-metadata-'));
             const projectRoot = fs.realpathSync(tmpRoot);
             const basePath = path.join(tmpRoot, '.taskforce');
@@ -7303,7 +8476,7 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(store.get('asset-sync-doc-meta-1', 'workspace-local')).toEqual(expect.objectContaining({
-                referenceNumber: 9
+                referenceNumber: 42
             }));
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
@@ -7366,7 +8539,7 @@ describe('Server Routes', () => {
             }));
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
-        it('POST /api/taskforce/sync/workspace/apply-local should preserve image references during normal sync when content is unchanged', async () => {
+        it('POST /api/taskforce/sync/workspace/apply-local should adopt cloud image references during normal sync even when content is unchanged', async () => {
             const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-sync-apply-image-metadata-'));
             const projectRoot = fs.realpathSync(tmpRoot);
             const basePath = path.join(tmpRoot, '.taskforce');
@@ -7418,7 +8591,7 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(store.get('asset-sync-image-meta-1', 'workspace-local')).toEqual(expect.objectContaining({
-                referenceNumber: 9
+                referenceNumber: 42
             }));
             fs.rmSync(dbRoot, { recursive: true, force: true });
         });
@@ -7735,15 +8908,213 @@ describe('Server Routes', () => {
             const res2 = createMockRes();
             await match?.handler(req2, res2, {});
             expect(core.applyWorkspaceSyncSnapshot).toHaveBeenCalledTimes(1);
-            expect(res2.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
-            const secondPayload = JSON.parse(String(res2.end.mock.calls.at(-1)?.[0] || '{}'));
-            expect(secondPayload.emittedEventIds).toEqual(firstPayload.emittedEventIds);
-            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
-                action: 'sync-workspace-push-success'
-            }));
-            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
-                action: 'sync-workspace-push-idempotent-replay'
-            }));
+            expect(res2.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const secondPayload = JSON.parse(String(res2.end.mock.calls.at(-1)?.[0] || '{}'));
+            expect(secondPayload.emittedEventIds).toEqual(firstPayload.emittedEventIds);
+            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'sync-workspace-push-success'
+            }));
+            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'sync-workspace-push-idempotent-replay'
+            }));
+        });
+        it('POST /api/taskforce/sync/workspace/push should still return success when idempotency persistence 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-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
+            });
+            core.writePushIdempotency.mockImplementationOnce(() => {
+                throw new Error('disk full');
+            });
+            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: '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(res.end).toHaveBeenCalledWith(expect.stringContaining('"success":true'));
+            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'sync-workspace-push-idempotency-write-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 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 = {
@@ -8775,6 +10146,127 @@ describe('Server Routes', () => {
             expect(res.setHeader).toHaveBeenCalledWith('Set-Cookie', expect.stringContaining('taskforce_session='));
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
+        it('POST /api/taskforce/session/workspace should allow a read-only user to switch to another active workspace', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            const cookie = createSessionTokenCookie('session-read-only', authConfig, {
+                role: 'read-only',
+                workspaceId: 'workspace-shared',
+                userId: 'user-1'
+            });
+            core.listUserWorkspaces.mockReturnValue([
+                {
+                    id: 'workspace-shared',
+                    slug: 'workspace-shared',
+                    name: 'Shared Workspace',
+                    description: null,
+                    role: 'read-only',
+                    status: 'active',
+                    betaAccess: true
+                },
+                {
+                    id: 'workspace-home',
+                    slug: 'workspace-home',
+                    name: 'Home Workspace',
+                    description: null,
+                    role: 'owner',
+                    status: 'active',
+                    betaAccess: true
+                }
+            ]);
+            core.resolveUserAccess.mockReturnValue({
+                userId: 'user-1',
+                workspaceId: 'workspace-home',
+                role: 'owner',
+                permissionMode: 'read-write',
+                disabled: false,
+                betaAccess: true
+            });
+            const match = matchRoute('POST', '/api/taskforce/session/workspace', routes);
+            const req = createMockReq('POST', '/api/taskforce/session/workspace', {
+                workspaceId: 'workspace-home'
+            }, {
+                cookie
+            });
+            const res = createMockRes();
+            res.setHeader = vi.fn();
+            await match?.handler(req, res, {});
+            expect(core.resolveUserAccess).toHaveBeenCalledWith('user-1', 'workspace-home', 'read-only');
+            expect(res.setHeader).toHaveBeenCalledWith('Set-Cookie', expect.stringContaining('taskforce_session='));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(String(res.end.mock.calls[0]?.[0] || '{}'));
+            expect(payload).toMatchObject({ success: true, workspaceId: 'workspace-home', role: 'owner' });
+        });
+        it('POST /api/taskforce/session/workspace should allow switching into an active read-only workspace', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            const cookie = createSessionTokenCookie('session-member', authConfig, {
+                role: 'owner',
+                workspaceId: 'workspace-home',
+                userId: 'user-1'
+            });
+            core.listUserWorkspaces.mockReturnValue([
+                {
+                    id: 'workspace-home',
+                    slug: 'workspace-home',
+                    name: 'Home Workspace',
+                    description: null,
+                    role: 'owner',
+                    status: 'active',
+                    betaAccess: true
+                },
+                {
+                    id: 'workspace-shared',
+                    slug: 'workspace-shared',
+                    name: 'Shared Workspace',
+                    description: null,
+                    role: 'read-only',
+                    status: 'active',
+                    betaAccess: true
+                }
+            ]);
+            core.resolveUserAccess.mockReturnValue({
+                userId: 'user-1',
+                workspaceId: 'workspace-shared',
+                role: 'read-only',
+                permissionMode: 'read-only',
+                disabled: false,
+                betaAccess: true
+            });
+            const match = matchRoute('POST', '/api/taskforce/session/workspace', routes);
+            const req = createMockReq('POST', '/api/taskforce/session/workspace', {
+                workspaceId: 'workspace-shared'
+            }, {
+                cookie
+            });
+            const res = createMockRes();
+            res.setHeader = vi.fn();
+            await match?.handler(req, res, {});
+            expect(res.setHeader).toHaveBeenCalledWith('Set-Cookie', expect.stringContaining('taskforce_session='));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(String(res.end.mock.calls[0]?.[0] || '{}'));
+            expect(payload).toMatchObject({ success: true, workspaceId: 'workspace-shared', role: 'read-only' });
+        });
         it('POST /api/taskforce/session/workspace should be disabled in local runtime', async () => {
             const authConfig = {
                 runtimeMode: 'local',
@@ -8871,6 +10363,7 @@ describe('Server Routes', () => {
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.authenticated).toBe(true);
             expect(payload.betaAccess).toBe(false);
+            expect(res.setHeader).toHaveBeenCalledWith('Server-Timing', expect.stringContaining('auth-session'));
             expect(core.getUserBetaAccess).toHaveBeenCalledWith('u-no-workspace');
         });
         it('GET /api/taskforce/auth/session should expose avatarUrl from the resolved profile', async () => {
@@ -9081,6 +10574,74 @@ describe('Server Routes', () => {
                 mimeType: 'image/png'
             }));
         });
+        it('POST /api/taskforce/auth/profile/avatar/upload should store the avatar body through object storage', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            const fetchMock = vi.fn().mockResolvedValue({
+                ok: true,
+                status: 200,
+                statusText: 'OK',
+                text: async () => ''
+            });
+            vi.stubGlobal('fetch', fetchMock);
+            const routesWithStorage = createRoutes(core, {
+                authConfig,
+                objectStorage: {
+                    provider: 'r2',
+                    r2: {
+                        accountId: 'acct-1',
+                        bucket: 'taskforce-docs',
+                        endpoint: 'https://example.r2.cloudflarestorage.com',
+                        accessKeyId: 'access-key-1',
+                        secretAccessKey: 'secret-key-1',
+                        keyPrefix: 'taskforce',
+                        signedUploadTtlSeconds: 600,
+                        signedDownloadTtlSeconds: 300
+                    }
+                }
+            });
+            core.getUserAvatarUploadDraft.mockReturnValueOnce({
+                draftId: 'avatar-draft-1',
+                userId: 'u1',
+                storageKey: 'users/u1/profile/avatar/avatar-draft-1-headshot.png',
+                mimeType: 'image/png',
+                finalizedAt: null,
+                discardedAt: null
+            });
+            const cookie = createSessionTokenCookie('session-avatar-upload', authConfig, {
+                userId: 'u1',
+                role: 'member',
+                workspaceId: 'workspace-1'
+            });
+            const match = matchRoute('POST', '/api/taskforce/auth/profile/avatar/upload', routesWithStorage);
+            const req = createMockReq('POST', '/api/taskforce/auth/profile/avatar/upload', Buffer.from([1, 2, 3, 4]), {
+                cookie,
+                'content-type': 'image/png',
+                'x-taskforce-avatar-draft-id': 'avatar-draft-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.success).toBe(true);
+            expect(payload.draftId).toBe('avatar-draft-1');
+            const r2Call = fetchMock.mock.calls[0];
+            expect(String(r2Call?.[0])).toContain('https://example.r2.cloudflarestorage.com/taskforce-docs/taskforce/users/u1/profile/avatar/avatar-draft-1-headshot.png');
+            expect(r2Call?.[1]).toEqual(expect.objectContaining({
+                method: 'PUT',
+                body: expect.any(Uint8Array)
+            }));
+            expect((r2Call?.[1]?.headers)['content-type']).toBe('image/png');
+            vi.unstubAllGlobals();
+        });
         it('POST /api/taskforce/auth/profile/avatar/finalize should validate and finalize the uploaded draft', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -9205,6 +10766,56 @@ describe('Server Routes', () => {
                 allowed: true
             });
         });
+        it('GET /api/taskforce/account/team-management-access should resolve against the authenticated session user and workspace', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValueOnce([
+                { id: 'workspace-auth-existing-home', slug: 'home', name: 'Home', description: null, role: 'owner', status: 'active', betaAccess: true },
+                { id: 'workspace-invited', slug: 'invited', name: 'Invited', description: null, role: 'member', status: 'active', betaAccess: true }
+            ]);
+            core.resolveUserAccess.mockImplementation((userId, workspaceId, role) => ({
+                userId,
+                workspaceId,
+                role: userId === 'joined-member' && workspaceId === 'workspace-invited' ? 'member' : role,
+                disabled: false,
+                betaAccess: true
+            }));
+            const cookie = createSessionTokenCookie('session-joined-member', authConfig, {
+                userId: 'joined-member',
+                role: 'member',
+                workspaceId: 'workspace-invited'
+            });
+            const match = matchRoute('GET', '/api/taskforce/account/team-management-access', routes);
+            const req = createMockReq('GET', '/api/taskforce/account/team-management-access', undefined, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-user-id': 'workspace-auth-existing-home-owner',
+                'x-taskforce-workspace-id': 'workspace-auth-existing-home',
+                'x-taskforce-role': 'owner'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.resolveUserAccess).toHaveBeenCalledWith('joined-member', 'workspace-invited', 'member');
+            expect(core.getAccountEntitlementsPayload).toHaveBeenCalledWith({ userId: 'joined-member', workspaceId: 'workspace-invited' });
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload).toMatchObject({
+                workspaceId: 'workspace-invited',
+                role: 'member',
+                canManageWorkspace: false,
+                teamPlanMode: 'team',
+                allowed: false
+            });
+        });
         it('GET /api/taskforce/account/team-management-access should fall back to the hinted workspace role when local access cannot resolve the cloud user id', async () => {
             core.resolveUserAccess.mockReturnValueOnce(null);
             const match = matchRoute('GET', '/api/taskforce/account/team-management-access', routes);
@@ -9281,6 +10892,40 @@ describe('Server Routes', () => {
                 planSelectionRequired: false
             });
         });
+        it('GET /api/taskforce/account/ai-profile-seat-usage should return cloud-authoritative ai seat usage', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.countAiProfileUsage.mockReturnValueOnce({ used: 0, limit: 20, remaining: 20 });
+            const match = matchRoute('GET', '/api/taskforce/account/ai-profile-seat-usage', routes);
+            const cookie = createSessionTokenCookie('session-ai-seat-usage', authConfig, {
+                userId: 'u1',
+                role: 'owner',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('GET', '/api/taskforce/account/ai-profile-seat-usage?workspaceId=workspace-1', undefined, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-user-id': 'u1',
+                'x-taskforce-role': 'owner',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.countAiProfileUsage).toHaveBeenCalledWith('workspace-1');
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.aiProfileSeatUsage).toEqual({ used: 0, limit: 20, remaining: 20 });
+        });
         it('GET /api/taskforce/account/access-status should return pending plan-selection gate', async () => {
             core.getAccountAccessStatus.mockReturnValueOnce({
                 gate: 'plan_selection_required',
@@ -9353,6 +10998,78 @@ describe('Server Routes', () => {
                 error.code = 'ENTITLEMENT_NOT_FOUND';
                 throw error;
             });
+            core.countAiProfileUsage.mockReturnValueOnce({ used: 0, limit: 20, remaining: 20 });
+            const match = matchRoute('GET', '/api/taskforce/account/profile-summary', routes);
+            const req = createMockReq('GET', '/api/taskforce/account/profile-summary?workspaceId=workspace-1', undefined, {
+                'x-taskforce-user-id': 'u1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload).toMatchObject({
+                planId: 'pro',
+                planVersionId: 'pro-v1',
+                entitlementState: 'checkout_pending',
+                gate: 'checkout_pending',
+                message: 'Complete checkout to continue.',
+                billingConflictCode: null,
+                planSelectionRequired: false,
+                workspaceId: 'workspace-1',
+                workspaceRole: 'owner',
+                canManageWorkspace: true,
+                teamPlanMode: 'personal',
+                teamManagementAllowed: false,
+                aiProfileSeatUsage: {
+                    used: 0,
+                    limit: 20,
+                    remaining: 20
+                }
+            });
+        });
+        it('GET /api/taskforce/account/profile-summary should not leak stale billing mirror plan identity when entitlement is missing', async () => {
+            core.resolveUserAccess.mockReturnValueOnce({
+                userId: 'u1',
+                workspaceId: 'workspace-1',
+                role: 'member',
+                disabled: false,
+                betaAccess: true
+            });
+            core.getAccountAccessStatus.mockReturnValueOnce({
+                gate: 'missing_entitlement',
+                hasEntitlement: false,
+                canAccessApp: false,
+                canAccessPlans: true,
+                planSelectionRequired: false,
+                message: 'No entitlement is linked to this account.',
+                entitlement: null
+            });
+            core.countAiProfileUsage.mockReturnValueOnce({ used: 0, limit: 20, remaining: 20 });
+            const baseDb = core.getDatabaseAdapter();
+            core.getDatabaseAdapter = vi.fn().mockReturnValue({
+                ...baseDb,
+                prepare: vi.fn((sql) => {
+                    if (sql.includes('FROM user_billing')) {
+                        return {
+                            get: () => ({
+                                stripe_status: 'active',
+                                stripe_customer_id: 'cus_stale',
+                                stripe_subscription_id: 'sub_stale',
+                                stripe_price_id: 'price_stale',
+                                billing_interval: 'month',
+                                entitlement_state: 'active',
+                                tier: 'team-5'
+                            })
+                        };
+                    }
+                    if (sql.includes('FROM plan_catalog')) {
+                        return {
+                            get: () => ({ display_name: 'Team 5' })
+                        };
+                    }
+                    return baseDb.prepare(sql);
+                })
+            });
             const match = matchRoute('GET', '/api/taskforce/account/profile-summary', routes);
             const req = createMockReq('GET', '/api/taskforce/account/profile-summary?workspaceId=workspace-1', undefined, {
                 'x-taskforce-user-id': 'u1'
@@ -9362,18 +11079,15 @@ describe('Server Routes', () => {
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload).toMatchObject({
-                planId: 'pro',
-                planVersionId: 'pro-v1',
-                entitlementState: 'checkout_pending',
-                gate: 'checkout_pending',
-                message: 'Complete checkout to continue.',
-                billingConflictCode: null,
+                planId: null,
+                planVersionId: null,
+                entitlementState: null,
+                gate: 'missing_entitlement',
+                message: 'No entitlement is linked to this account.',
                 planSelectionRequired: false,
-                workspaceId: 'workspace-1',
-                workspaceRole: 'owner',
-                canManageWorkspace: true,
-                teamPlanMode: 'personal',
-                teamManagementAllowed: false
+                stripeStatus: 'active',
+                stripeCustomerId: 'cus_stale',
+                stripeSubscriptionId: 'sub_stale'
             });
         });
         it('GET /api/taskforce/account/entitlements should surface checkout-pending gate when billing is not complete', async () => {
@@ -9445,6 +11159,20 @@ describe('Server Routes', () => {
             expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"code":"PLAN_SELECTION_REQUIRED"'));
             expect(core.listTasks).not.toHaveBeenCalled();
         });
+        it('GET /api/taskforce/tasks should require authenticated cloud users', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listTasks.mockReturnValue({ tasks: [] });
+            const match = matchRoute('GET', '/api/taskforce/tasks', routes);
+            const req = createMockReq('GET', '/api/taskforce/tasks', undefined, {
+                'x-taskforce-runtime-mode': 'cloud'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(401, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"Authentication required."'));
+            expect(core.listTasks).not.toHaveBeenCalled();
+        });
         it('GET /api/taskforce/tasks should block authenticated users with missing entitlements', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -9552,17 +11280,31 @@ describe('Server Routes', () => {
             try {
                 core.getTenantId = vi.fn().mockReturnValue('default');
                 core.getDatabaseAdapter = vi.fn().mockReturnValue({
-                    prepare: vi.fn().mockReturnValue({
-                        all: vi.fn().mockReturnValue([
-                            {
-                                plan_version_id: 'free-v1',
-                                billing_interval: 'month',
-                                stripe_price_id: 'free:free-v1:month',
-                                pricing_type: 'free',
-                                unit_amount: 0,
-                                currency: null
-                            }
-                        ])
+                    prepare: vi.fn().mockImplementation((sql) => {
+                        if (sql.includes('FROM billing_price_mappings')) {
+                            return {
+                                get: vi.fn().mockReturnValue({
+                                    count: 1,
+                                    max_updated_at: '2026-01-01T00:00:00.000Z'
+                                }),
+                                all: vi.fn().mockReturnValue([
+                                    {
+                                        plan_version_id: 'free-v1',
+                                        billing_interval: 'month',
+                                        stripe_price_id: 'free:free-v1:month',
+                                        pricing_type: 'free',
+                                        unit_amount: 0,
+                                        currency: null
+                                    }
+                                ])
+                            };
+                        }
+                        return {
+                            get: vi.fn().mockReturnValue({
+                                count: 0,
+                                max_updated_at: null
+                            })
+                        };
                     })
                 });
                 core.listPlanCatalog.mockReturnValueOnce([
@@ -9582,6 +11324,7 @@ describe('Server Routes', () => {
                         }
                     }
                 ]);
+                core.listPlanFeatureCatalog = vi.fn().mockReturnValue([]);
                 routes = createRoutes(core);
                 const match = matchRoute('GET', '/api/taskforce/public/pricing', routes);
                 const req = createMockReq('GET', '/api/taskforce/public/pricing', undefined, {
@@ -9593,7 +11336,15 @@ describe('Server Routes', () => {
                 const payload = JSON.parse(String(res.end.mock.calls[0][0]));
                 expect(payload.plans).toHaveLength(1);
                 expect(payload.plans[0].features).toEqual([
-                    { featureKey: 'ai.assistance', access: 'enabled', config: {} }
+                    {
+                        featureKey: 'ai.assistance',
+                        access: 'enabled',
+                        config: {},
+                        label: null,
+                        description: null,
+                        publicLabel: null,
+                        publicDescription: null
+                    }
                 ]);
             }
             finally {
@@ -9625,6 +11376,7 @@ describe('Server Routes', () => {
             expect(core.upsertPlanCatalog).toHaveBeenCalledWith({
                 planId: 'enterprise',
                 displayName: 'Enterprise',
+                description: undefined,
                 status: 'active',
                 initialTrialDays: 0,
                 initialMode: undefined,
@@ -9644,6 +11396,42 @@ describe('Server Routes', () => {
             expect(core.listPlanCatalog).toHaveBeenCalled();
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
+        it('GET /api/platform/onboarding-plan-options should return onboarding plan options for system admin', async () => {
+            core.listOnboardingPlanOptions = vi.fn().mockReturnValue([
+                {
+                    planId: 'free',
+                    planDisplayName: 'Free',
+                    defaultPlanVersionId: 'free-v1',
+                    defaultVersionNumber: 1,
+                    planStatus: 'active',
+                    supportsAutoGrantFree: true,
+                    supportsAutoStartTrial: false
+                }
+            ]);
+            const match = matchRoute('GET', '/api/platform/onboarding-plan-options', routes);
+            const req = createMockReq('GET', '/api/platform/onboarding-plan-options', undefined, {
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-system-role': 'system_admin'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.listOnboardingPlanOptions).toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(JSON.parse(res.end.mock.calls[0]?.[0] || '{}')).toEqual({
+                success: true,
+                options: [
+                    {
+                        planId: 'free',
+                        planDisplayName: 'Free',
+                        defaultPlanVersionId: 'free-v1',
+                        defaultVersionNumber: 1,
+                        planStatus: 'active',
+                        supportsAutoGrantFree: true,
+                        supportsAutoStartTrial: false
+                    }
+                ]
+            });
+        });
         it('GET /api/platform/plans/:planId/versions should list versions', async () => {
             const match = matchRoute('GET', '/api/platform/plans/collab/versions', routes);
             const req = createMockReq('GET', '/api/platform/plans/collab/versions', undefined, {
@@ -9702,6 +11490,37 @@ describe('Server Routes', () => {
             expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"featureKey":"collaboration.team_management"'));
             expect(res.end).not.toHaveBeenCalledWith(expect.stringContaining('"featureKey":"collaboration.invites"'));
         });
+        it('PATCH /api/platform/features/:featureKey should update public marketing copy', async () => {
+            core.updatePlanFeatureCatalogMarketingCopy = vi.fn().mockReturnValue({
+                featureKey: 'collaboration.ai_profiles',
+                label: 'AI Profiles',
+                description: 'Allow registered AI collaborator profiles with an optional per-workspace limit.',
+                publicLabel: 'AI teammates',
+                publicDescription: 'Add reusable AI teammates to your workspace.',
+                publicDisplayOrder: 20,
+                allowedAccessModes: ['enabled', 'limited', 'disabled'],
+                configTemplate: { maxAiProfiles: 1 }
+            });
+            const match = matchRoute('PATCH', '/api/platform/features/collaboration.ai_profiles', routes);
+            const req = createMockReq('PATCH', '/api/platform/features/collaboration.ai_profiles', {
+                publicLabel: 'AI teammates',
+                publicDescription: 'Add reusable AI teammates to your workspace.',
+                publicDisplayOrder: 20
+            }, {
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-system-role': 'system_admin'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { featureKey: 'collaboration.ai_profiles' });
+            expect(core.updatePlanFeatureCatalogMarketingCopy).toHaveBeenCalledWith({
+                featureKey: 'collaboration.ai_profiles',
+                publicLabel: 'AI teammates',
+                publicDescription: 'Add reusable AI teammates to your workspace.',
+                publicDisplayOrder: 20
+            });
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"publicLabel":"AI teammates"'));
+        });
         it('PATCH /api/platform/plans/:planId/versions/:versionId/features should return normalized dependency state', async () => {
             core.updatePlanVersionFeatures.mockReturnValueOnce({
                 planVersionId: 'collab-v1',
@@ -9831,13 +11650,20 @@ describe('Server Routes', () => {
                     updatedAt: '2026-02-01T00:00:00.000Z'
                 }
             ]);
+            core.countSystemUsers.mockReturnValueOnce(1);
             const match = matchRoute('GET', '/api/taskforce/admin/system-users', routes);
-            const req = createMockReq('GET', '/api/taskforce/admin/system-users', undefined, { 'x-taskforce-system-role': 'system_admin' });
+            const req = createMockReq('GET', '/api/taskforce/admin/system-users?q=u1&sort=oldest&limit=25&offset=50', undefined, { 'x-taskforce-system-role': 'system_admin' });
             const res = createMockRes();
             await match?.handler(req, res, {});
-            expect(core.listSystemUsers).toHaveBeenCalled();
+            expect(core.countSystemUsers).toHaveBeenCalledWith({ query: 'u1' });
+            expect(core.listSystemUsers).toHaveBeenCalledWith({ query: 'u1', sort: 'oldest', limit: 25, offset: 50 });
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
-            expect(res.end).toHaveBeenCalledWith(expect.stringContaining('"users"'));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.users).toHaveLength(1);
+            expect(payload.total).toBe(1);
+            expect(payload.limit).toBe(25);
+            expect(payload.offset).toBe(50);
+            expect(payload.hasMore).toBe(false);
         });
         it('GET /api/taskforce/admin/system-users should allow authenticated system admin without role header', async () => {
             const authConfig = {
@@ -9863,7 +11689,8 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.getSystemRole).toHaveBeenCalledWith('admin-user');
-            expect(core.listSystemUsers).toHaveBeenCalled();
+            expect(core.countSystemUsers).toHaveBeenCalledWith({ query: '' });
+            expect(core.listSystemUsers).toHaveBeenCalledWith({ query: '', sort: 'newest', limit: 50, offset: 0 });
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
         it('GET /api/taskforce/admin/audit-logs should return events for admins', async () => {
@@ -10125,6 +11952,266 @@ describe('Server Routes', () => {
             expect(matchRoute('POST', '/api/taskforce/admin/users/invite', routes)).not.toBeNull();
             expect(matchRoute('PATCH', '/api/taskforce/admin/users/u1/role', routes)).not.toBeNull();
             expect(matchRoute('GET', '/api/taskforce/admin/workspace-audit-logs', routes)).not.toBeNull();
+            expect(matchRoute('POST', '/api/taskforce/workspace/ai-profiles/avatar', routes)).not.toBeNull();
+        });
+        it('POST /api/taskforce/admin/users/invite should authorize against the target workspace', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([
+                { id: 'workspace-home', slug: 'home', name: 'Home', role: 'owner', status: 'active', betaAccess: true },
+                { id: 'workspace-shared', slug: 'shared', name: 'Shared', role: 'member', status: 'active', betaAccess: true }
+            ]);
+            core.listWorkspaceUsers.mockImplementation((workspaceId) => {
+                if (workspaceId === 'workspace-home') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'owner',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                if (workspaceId === 'workspace-shared') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'member',
+                            permissionMode: 'read-only',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                return [];
+            });
+            core.inviteWorkspaceUser.mockReturnValue({
+                userId: 'invited-user',
+                email: 'invited@example.com',
+                role: 'member',
+                status: 'invited',
+                disabled: false
+            });
+            const cookie = createSessionTokenCookie('session-target-invite-deny', authConfig, {
+                userId: 'actor-user',
+                role: 'owner',
+                workspaceId: 'workspace-home'
+            });
+            const match = matchRoute('POST', '/api/taskforce/admin/users/invite', routes);
+            const req = createMockReq('POST', '/api/taskforce/admin/users/invite', {
+                workspaceId: 'workspace-shared',
+                email: 'invited@example.com',
+                role: 'member'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'owner',
+                'x-taskforce-user-id': 'actor-user',
+                'x-taskforce-workspace-id': 'workspace-home'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.inviteWorkspaceUser).not.toHaveBeenCalled();
+            expect(core.evaluateFeatureAccess).not.toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(403, expect.any(Object));
+        });
+        it('POST /api/taskforce/admin/users/invite should resolve feature access and inviter identity from the authenticated session user', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listWorkspaceUsers.mockImplementation((workspaceId) => {
+                if (workspaceId === 'workspace-shared') {
+                    return [{
+                            userId: 'joined-admin',
+                            email: 'joined-admin@example.com',
+                            displayName: 'Joined Admin',
+                            role: 'admin',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                return [];
+            });
+            core.evaluateFeatureAccess.mockImplementation(({ userId }) => ({
+                allowed: userId === 'joined-admin',
+                reasonCode: userId === 'joined-admin' ? undefined : 'ACCOUNT_ENTITLEMENT_REQUIRED'
+            }));
+            core.inviteWorkspaceUser.mockReturnValue({
+                userId: 'invited-user',
+                email: 'invited@example.com',
+                role: 'member',
+                status: 'invited',
+                disabled: false
+            });
+            core.requestInviteAcceptance.mockReturnValue({ token: 'invite-token-1' });
+            core.getWorkspaceProfile.mockReturnValue({
+                id: 'workspace-shared',
+                name: 'Shared Workspace'
+            });
+            core.resolveUserIdentity.mockReturnValue({
+                userId: 'joined-admin',
+                email: 'joined-admin@example.com',
+                displayName: 'Joined Admin'
+            });
+            const cookie = createSessionTokenCookie('session-target-invite-identity', authConfig, {
+                userId: 'joined-admin',
+                role: 'admin',
+                workspaceId: 'workspace-shared'
+            });
+            const match = matchRoute('POST', '/api/taskforce/admin/users/invite', routes);
+            const req = createMockReq('POST', '/api/taskforce/admin/users/invite', {
+                workspaceId: 'workspace-shared',
+                email: 'invited@example.com',
+                role: 'member'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'owner',
+                'x-taskforce-user-id': 'workspace-auth-existing-home-owner',
+                'x-taskforce-workspace-id': 'workspace-auth-existing-home'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.evaluateFeatureAccess).toHaveBeenCalledWith(expect.objectContaining({
+                userId: 'joined-admin',
+                workspaceId: 'workspace-shared',
+                featureKey: 'collaboration.invites'
+            }));
+            expect(core.resolveUserIdentity).toHaveBeenCalledWith('joined-admin');
+            expect(core.inviteWorkspaceUser).toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        });
+        it('PATCH /api/taskforce/admin/users/:id/role should reject active-workspace admins who are only target-workspace members', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([
+                { id: 'workspace-home', slug: 'home', name: 'Home', role: 'owner', status: 'active', betaAccess: true },
+                { id: 'workspace-shared', slug: 'shared', name: 'Shared', role: 'member', status: 'active', betaAccess: true }
+            ]);
+            core.listWorkspaceUsers.mockImplementation((workspaceId) => {
+                if (workspaceId === 'workspace-home') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'owner',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                if (workspaceId === 'workspace-shared') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'member',
+                            permissionMode: 'read-only',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                return [];
+            });
+            core.updateWorkspaceUserRole.mockReturnValue(true);
+            const cookie = createSessionTokenCookie('session-target-role-deny', authConfig, {
+                userId: 'actor-user',
+                role: 'owner',
+                workspaceId: 'workspace-home'
+            });
+            const match = matchRoute('PATCH', '/api/taskforce/admin/users/target-user/role', routes);
+            const req = createMockReq('PATCH', '/api/taskforce/admin/users/target-user/role', {
+                workspaceId: 'workspace-shared',
+                role: 'admin'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'owner',
+                'x-taskforce-user-id': 'actor-user',
+                'x-taskforce-workspace-id': 'workspace-home'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { id: 'target-user' });
+            expect(core.updateWorkspaceUserRole).not.toHaveBeenCalled();
+            expect(core.evaluateFeatureAccess).not.toHaveBeenCalled();
+            expect(res.writeHead).toHaveBeenCalledWith(403, expect.any(Object));
+        });
+        it('PATCH /api/taskforce/admin/users/:id/role should allow target-workspace admins with a different active workspace', async () => {
+            const authConfig = createCloudAuthConfig();
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([
+                { id: 'workspace-home', slug: 'home', name: 'Home', role: 'member', status: 'active', betaAccess: true },
+                { id: 'workspace-shared', slug: 'shared', name: 'Shared', role: 'admin', status: 'active', betaAccess: true }
+            ]);
+            core.listWorkspaceUsers.mockImplementation((workspaceId) => {
+                if (workspaceId === 'workspace-home') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'member',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                if (workspaceId === 'workspace-shared') {
+                    return [{
+                            userId: 'actor-user',
+                            email: 'actor@example.com',
+                            displayName: 'Actor',
+                            role: 'admin',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }];
+                }
+                return [];
+            });
+            core.updateWorkspaceUserRole.mockReturnValue(true);
+            const cookie = createSessionTokenCookie('session-target-role-allow', authConfig, {
+                userId: 'actor-user',
+                role: 'member',
+                workspaceId: 'workspace-home'
+            });
+            const match = matchRoute('PATCH', '/api/taskforce/admin/users/target-user/role', routes);
+            const req = createMockReq('PATCH', '/api/taskforce/admin/users/target-user/role', {
+                workspaceId: 'workspace-shared',
+                role: 'admin'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'member',
+                'x-taskforce-user-id': 'actor-user',
+                'x-taskforce-workspace-id': 'workspace-home'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, { id: 'target-user' });
+            expect(core.evaluateFeatureAccess).toHaveBeenCalledWith({
+                userId: 'actor-user',
+                workspaceId: 'workspace-shared',
+                featureKey: 'collaboration.team_management'
+            });
+            expect(core.updateWorkspaceUserRole).toHaveBeenCalledWith('target-user', 'workspace-shared', 'admin');
+            expect(core.addAdminAuditLog).toHaveBeenCalledWith(expect.objectContaining({
+                action: 'update-workspace-user-role',
+                actorUserId: 'actor-user',
+                actorRole: 'admin',
+                workspaceId: 'workspace-shared',
+                details: expect.objectContaining({
+                    workspaceId: 'workspace-shared',
+                    targetUserId: 'target-user'
+                })
+            }));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
         });
         it('GET /api/taskforce/workspace/assignee-options should reject unauthenticated cloud requests', async () => {
             const authConfig = {
@@ -10219,6 +12306,7 @@ describe('Server Routes', () => {
                     userId: 'member-1',
                     email: 'member1@example.com',
                     displayName: 'Member One',
+                    avatarUrl: '/api/taskforce/context/users%2Fmember-1%2Fprofile%2Favatar%2Fheadshot.webp',
                     role: 'member',
                     permissionMode: 'read-write',
                     betaAccess: true,
@@ -10240,11 +12328,14 @@ describe('Server Routes', () => {
                     provider: 'OpenAI',
                     model: 'gpt-5.4',
                     surfaceType: 'coding_tool',
+                    seatScope: null,
+                    archivedAt: null,
                     createdAt: '2026-03-01T00:00:00.000Z',
                     updatedAt: '2026-03-01T00:00:00.000Z',
                     lastActiveAt: null
                 }
             ]);
+            core.countAiProfileUsage.mockReturnValue({ used: 1, limit: 3, remaining: 2 });
             const match = matchRoute('GET', '/api/taskforce/workspace/assignee-options', routes);
             const cookie = createSessionTokenCookie('session-member-assignees', authConfig, {
                 userId: 'member-user',
@@ -10261,9 +12352,14 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.listWorkspaceUsers).toHaveBeenCalledWith('workspace-1');
-            expect(core.listAiProfiles).toHaveBeenCalledWith('workspace-1');
+            expect(core.listAiProfiles).toHaveBeenCalledWith('workspace-1', expect.objectContaining({
+                diagnostics: expect.any(Object)
+            }));
+            expect(core.countAiProfileUsage).toHaveBeenCalledWith('workspace-1');
+            expect(res.setHeader).toHaveBeenCalledWith('Server-Timing', expect.stringContaining('assignee-options'));
             expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
             const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.aiProfileSeatUsage).toEqual({ used: 1, limit: 3, remaining: 2 });
             expect(payload.assignees).toEqual([
                 {
                     value: 'member-1',
@@ -10274,6 +12370,7 @@ describe('Server Routes', () => {
                     userId: 'member-1',
                     email: 'member1@example.com',
                     displayName: 'Member One',
+                    avatarUrl: '/api/taskforce/context/users%2Fmember-1%2Fprofile%2Favatar%2Fheadshot.webp',
                     status: 'active',
                     disabled: false
                 },
@@ -10283,12 +12380,16 @@ describe('Server Routes', () => {
                     username: 'codex',
                     icon: 'Bot',
                     color: '#ef6c00',
+                    avatarUrl: null,
+                    avatarSourceUrl: null,
                     kind: 'agent',
                     description: 'Builds product code',
                     role: 'Implementer',
                     provider: 'OpenAI',
                     model: 'gpt-5.4',
                     surfaceType: 'coding_tool',
+                    seatScope: null,
+                    archivedAt: null,
                     createdAt: '2026-03-01T00:00:00.000Z',
                     updatedAt: '2026-03-01T00:00:00.000Z',
                     lastActiveAt: null
@@ -10328,6 +12429,7 @@ describe('Server Routes', () => {
                     lastActiveAt: null
                 }
             ]);
+            core.countAiProfileUsage.mockReturnValue({ used: 1, limit: 3, remaining: 2 });
             const match = matchRoute('GET', '/api/taskforce/workspace/assignee-options', routes);
             const cookie = createSessionTokenCookie('session-admin-assignees', authConfig, {
                 userId: 'admin-user',
@@ -10344,6 +12446,7 @@ describe('Server Routes', () => {
             const res = createMockRes();
             await match?.handler(req, res, {});
             const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.aiProfileSeatUsage).toEqual({ used: 1, limit: 3, remaining: 2 });
             expect(payload.assignees).toEqual([
                 expect.objectContaining({
                     value: 'ai-profile-1',
@@ -10351,6 +12454,198 @@ describe('Server Routes', () => {
                 })
             ]);
         });
+        it('POST /api/taskforce/workspace/ai-profiles/archive should archive active profiles for workspace admins', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.archiveAiProfile.mockReturnValue({
+                id: 'ai-profile-1',
+                workspaceId: 'workspace-1',
+                profileToken: 'tfp_codex_sync',
+                name: 'Codex',
+                username: 'codex',
+                icon: 'Bot',
+                color: '#ef6c00',
+                description: 'Builds product code',
+                role: 'Implementer',
+                provider: 'OpenAI',
+                model: 'gpt-5.4',
+                surfaceType: 'coding_tool',
+                archivedAt: '2026-04-19T17:00:00.000Z',
+                archivedBy: 'admin-user',
+                archivedReason: 'manual_archive',
+                mergedIntoProfileId: null,
+                createdAt: '2026-03-01T00:00:00.000Z',
+                updatedAt: '2026-04-19T17:00:00.000Z',
+                lastActiveAt: null
+            });
+            const match = matchRoute('POST', '/api/taskforce/workspace/ai-profiles/archive', routes);
+            const cookie = createSessionTokenCookie('session-admin-archive-ai-profile', authConfig, {
+                userId: 'admin-user',
+                role: 'admin',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('POST', '/api/taskforce/workspace/ai-profiles/archive', {
+                profileId: 'ai-profile-1',
+                reason: 'manual_archive'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'admin',
+                'x-taskforce-user-id': 'admin-user',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.archiveAiProfile).toHaveBeenCalledWith({
+                workspaceId: 'workspace-1',
+                profileId: 'ai-profile-1',
+                archivedBy: 'admin-user',
+                reason: 'manual_archive'
+            });
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.profile).toEqual(expect.objectContaining({
+                id: 'ai-profile-1',
+                archivedReason: 'manual_archive'
+            }));
+        });
+        it('POST /api/taskforce/workspace/ai-profiles/archive should honor actual owner membership even when the request role is stale', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            core.listUserWorkspaces.mockReturnValue([
+                {
+                    id: 'workspace-1',
+                    slug: 'workspace-1',
+                    name: 'Workspace 1',
+                    description: null,
+                    role: 'owner',
+                    status: 'active',
+                    betaAccess: true
+                }
+            ]);
+            core.listWorkspaceUsers.mockReturnValue([
+                {
+                    userId: 'owner-user',
+                    email: 'owner@example.com',
+                    displayName: 'Owner User',
+                    role: 'owner',
+                    permissionMode: 'read-write',
+                    betaAccess: true,
+                    status: 'active',
+                    disabled: false
+                }
+            ]);
+            core.archiveAiProfile.mockReturnValue({
+                id: 'ai-profile-1',
+                workspaceId: 'workspace-1',
+                profileToken: 'tfp_codex_sync',
+                name: 'Codex',
+                username: 'codex',
+                icon: 'Bot',
+                color: '#ef6c00',
+                description: 'Builds product code',
+                role: 'Implementer',
+                provider: 'OpenAI',
+                model: 'gpt-5.4',
+                surfaceType: 'coding_tool',
+                archivedAt: '2026-04-19T17:00:00.000Z',
+                archivedBy: 'owner-user',
+                archivedReason: 'manual_archive',
+                mergedIntoProfileId: null,
+                createdAt: '2026-03-01T00:00:00.000Z',
+                updatedAt: '2026-04-19T17:00:00.000Z',
+                lastActiveAt: null
+            });
+            const match = matchRoute('POST', '/api/taskforce/workspace/ai-profiles/archive', routes);
+            const cookie = createSessionTokenCookie('session-owner-archive', authConfig, {
+                userId: 'owner-user',
+                role: 'member',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('POST', '/api/taskforce/workspace/ai-profiles/archive', {
+                profileId: 'ai-profile-1'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'member',
+                'x-taskforce-user-id': 'owner-user',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(core.archiveAiProfile).toHaveBeenCalledWith(expect.objectContaining({
+                workspaceId: 'workspace-1',
+                profileId: 'ai-profile-1',
+                archivedBy: 'owner-user'
+            }));
+            expect(res.writeHead).toHaveBeenCalledWith(200, expect.any(Object));
+        });
+        it('POST /api/taskforce/workspace/ai-profiles/archive should surface open-task conflicts', async () => {
+            const authConfig = {
+                runtimeMode: 'cloud',
+                enabled: true,
+                requiredForApi: true,
+                excludedPaths: ['/api/taskforce/health', '/api/taskforce/auth'],
+                defaultRole: 'member',
+                defaultWorkspaceId: 'default',
+                sessionCookieName: 'taskforce_session',
+                sessionSecret: 'test-secret',
+                sessionTtlSeconds: 3600
+            };
+            routes = createRoutes(core, { authConfig });
+            const error = new Error('This AI profile still owns open tasks. Reassign or close them before removing it from the roster.');
+            error.statusCode = 409;
+            error.details = { workspaceId: 'workspace-1', profileId: 'ai-profile-1', openTaskCount: 2 };
+            core.archiveAiProfile.mockImplementation(() => {
+                throw error;
+            });
+            const match = matchRoute('POST', '/api/taskforce/workspace/ai-profiles/archive', routes);
+            const cookie = createSessionTokenCookie('session-admin-archive-ai-profile-conflict', authConfig, {
+                userId: 'admin-user',
+                role: 'admin',
+                workspaceId: 'workspace-1'
+            });
+            const req = createMockReq('POST', '/api/taskforce/workspace/ai-profiles/archive', {
+                profileId: 'ai-profile-1',
+                reason: 'manual_archive'
+            }, {
+                cookie,
+                'x-taskforce-runtime-mode': 'cloud',
+                'x-taskforce-role': 'admin',
+                'x-taskforce-user-id': 'admin-user',
+                'x-taskforce-workspace-id': 'workspace-1'
+            });
+            const res = createMockRes();
+            await match?.handler(req, res, {});
+            expect(res.writeHead).toHaveBeenCalledWith(409, expect.any(Object));
+            const payload = JSON.parse(res.end.mock.calls[0][0]);
+            expect(payload.error).toContain('This AI profile still owns open tasks');
+            expect(payload.details).toEqual({
+                workspaceId: 'workspace-1',
+                profileId: 'ai-profile-1',
+                openTaskCount: 2
+            });
+        });
         it('GET /api/taskforce/admin/workspace-audit-logs should return events for workspace admins', async () => {
             const authConfig = {
                 runtimeMode: 'cloud',
@@ -10448,13 +12743,13 @@ describe('Server Routes', () => {
                 billing: {
                     onboardingPolicy: {
                         mode: 'auto_grant_free',
-                        planVersionId: 'starter-v1'
+                        planId: 'starter'
                     }
                 }
             });
             core.getOnboardingPolicy.mockReturnValue({
                 mode: 'auto_grant_free',
-                planVersionId: 'starter-v1'
+                planId: 'starter'
             });
             const match = matchRoute('GET', '/api/taskforce/admin/system-settings', routes);
             const req = createMockReq('GET', '/api/taskforce/admin/system-settings', undefined, { 'x-taskforce-role': 'admin' });
@@ -10462,9 +12757,9 @@ describe('Server Routes', () => {
             await match?.handler(req, res, {});
             const payload = JSON.parse(res.end.mock.calls[0][0]);
             expect(payload.status.onboardingPolicyMode).toBe('auto_grant_free');
-            expect(payload.status.onboardingPlanVersionId).toBe('starter-v1');
+            expect(payload.status.onboardingPlanId).toBe('starter');
             expect(payload.settings.onboardingPolicyMode).toBe('auto_grant_free');
-            expect(payload.settings.onboardingPlanVersionId).toBe('starter-v1');
+            expect(payload.settings.onboardingPlanId).toBe('starter');
         });
         it('POST /api/taskforce/admin/system-settings should persist onboarding policy fields', async () => {
             const match = matchRoute('POST', '/api/taskforce/admin/system-settings', routes);
@@ -10476,13 +12771,13 @@ describe('Server Routes', () => {
                 authRateLimitMaxRequests: 10,
                 authRateLimitWindowMs: 900000,
                 onboardingPolicyMode: 'auto_grant_free',
-                onboardingPlanVersionId: 'starter-v1'
+                onboardingPlanId: 'starter'
             }, { 'x-taskforce-role': 'admin' });
             const res = createMockRes();
             await match?.handler(req, res, {});
             expect(core.validateOnboardingPolicy).toHaveBeenCalledWith({
                 mode: 'auto_grant_free',
-                planVersionId: 'starter-v1'
+                planId: 'starter'
             });
             expect(core.updateGlobalSettings).toHaveBeenCalledWith({
                 auth: {
@@ -10496,7 +12791,7 @@ describe('Server Routes', () => {
                 billing: {
                     onboardingPolicy: {
                         mode: 'auto_grant_free',
-                        planVersionId: 'starter-v1'
+                        planId: 'starter'
                     }
                 }
             });
@@ -10504,7 +12799,7 @@ describe('Server Routes', () => {
         it('POST /api/taskforce/admin/system-settings should preserve onboarding policy when onboarding fields are omitted', async () => {
             core.getOnboardingPolicy.mockReturnValue({
                 mode: 'auto_grant_free',
-                planVersionId: 'starter-v1'
+                planId: 'starter'
             });
             const match = matchRoute('POST', '/api/taskforce/admin/system-settings', routes);
             const req = createMockReq('POST', '/api/taskforce/admin/system-settings', {
@@ -10519,7 +12814,7 @@ describe('Server Routes', () => {
             await match?.handler(req, res, {});
             expect(core.validateOnboardingPolicy).toHaveBeenCalledWith({
                 mode: 'auto_grant_free',
-                planVersionId: 'starter-v1'
+                planId: 'starter'
             });
             expect(core.updateGlobalSettings).toHaveBeenCalledWith({
                 auth: {
@@ -10533,7 +12828,7 @@ describe('Server Routes', () => {
                 billing: {
                     onboardingPolicy: {
                         mode: 'auto_grant_free',
-                        planVersionId: 'starter-v1'
+                        planId: 'starter'
                     }
                 }
             });
@@ -10646,13 +12941,13 @@ describe('Server Routes', () => {
         it('POST /api/taskforce/admin/system-settings should reject invalid onboarding settings', async () => {
             core.validateOnboardingPolicy.mockReturnValueOnce({
                 valid: false,
-                code: 'ONBOARDING_PLAN_VERSION_REQUIRED',
-                message: 'An onboarding plan version is required for the selected onboarding mode.'
+                code: 'ONBOARDING_PLAN_REQUIRED',
+                message: 'An onboarding plan is required for the selected onboarding mode.'
             });
             const match = matchRoute('POST', '/api/taskforce/admin/system-settings', routes);
             const req = createMockReq('POST', '/api/taskforce/admin/system-settings', {
                 onboardingPolicyMode: 'auto_grant_free',
-                onboardingPlanVersionId: null
+                onboardingPlanId: null
             }, { 'x-taskforce-role': 'admin' });
             const res = createMockRes();
             await match?.handler(req, res, {});