@taskforcehq/taskforce 0.3.170 → 0.3.301

package/dist/server/routes/admin.js

@@ -0,0 +1,2226 @@
+/**
+ * Admin and platform route module.
+ *
+ * Handles platform plan/entitlement management, system-level admin operations,
+ * cloud MCP endpoints (HTTP transport + OAuth 2.0 PKCE flow), and
+ * per-user MCP token/connector settings.
+ *
+ * Routes registered here:
+ *   GET/POST  /api/platform/plans
+ *   GET/POST  /api/platform/plans/:planId/versions
+ *   GET       /api/platform/features
+ *   GET/PATCH /api/platform/plans/:planId/versions/:versionId/features
+ *   GET/PATCH /api/platform/accounts/:accountId/entitlement
+ *   GET       /api/platform/accounts/:accountId/entitlement-history
+ *   GET       /api/platform/accounts/search
+ *   GET       /api/taskforce/admin/system-users
+ *   GET       /api/taskforce/admin/audit-logs
+ *   GET       /api/taskforce/admin/mcp-audit-logs
+ *   PATCH     /api/taskforce/admin/system-users/:id/role
+ *   GET       /api/taskforce/admin/collaboration-telemetry
+ *   PATCH     /api/taskforce/admin/system-users/:id/disable
+ *   PATCH     /api/taskforce/admin/system-users/:id/beta-access
+ *   GET/POST  /api/taskforce/admin/email-settings
+ *   GET       /api/taskforce/admin/email-settings/health
+ *   POST      /api/taskforce/admin/email-settings/test
+ *   GET/POST  /api/taskforce/admin/system-settings
+ *   GET/POST  /api/taskforce/admin/object-storage-settings
+ *   GET       /api/taskforce/admin/object-storage-telemetry
+ *   POST      /api/taskforce/admin/object-storage-self-test
+ *   GET       /api/taskforce/admin/quarantine
+ *   POST      /api/taskforce/admin/quarantine/delete
+ *   GET/POST  /api/taskforce/admin/storage-integrity-settings
+ *   POST      /api/taskforce/admin/storage-integrity/scan
+ *   GET       /api/taskforce/admin/storage-integrity/history
+ *   GET       /api/taskforce/admin/document-purge/history
+ *   POST      /api/taskforce/admin/storage-integrity/repair
+ *   POST      /api/taskforce/admin/workspace-repair/scan
+ *   POST      /api/taskforce/admin/workspace-repair/apply
+ *   POST/GET/DELETE/OPTIONS /mcp (+ /mcp/)
+ *   GET       /.well-known/oauth-authorization-server
+ *   GET       /.well-known/oauth-protected-resource
+ *   POST      /oauth/mcp/register
+ *   GET/POST  /oauth/mcp/authorize
+ *   POST      /oauth/mcp/token
+ *   GET/POST  /api/taskforce/settings/mcp/tokens (+ revoke, regenerate)
+ *   GET       /api/taskforce/settings/mcp/connectors
+ *   POST      /api/taskforce/settings/mcp/connectors/:id/disconnect
+ *   POST      /api/taskforce/settings/mcp/test-connection
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { TaskforceRuleError } from '../../core/Taskforce.js';
+import { parseJsonBody } from '../routes.js';
+import { resolveRequestAccess } from '../auth.js';
+import { resolveEffectiveEmailConfig, sendEmail } from '../email.js';
+import { WorkspaceAssetStore } from '../../storage/workspaceAssetStore.js';
+import { scanDocumentIntegrity } from '../../storage/documentIntegrity.js';
+import { normalizeStorageIntegrityScheduleSettings, resolveStorageIntegrityScheduleSettings, } from '../../storage/integritySchedule.js';
+import { resolveVirusScanConfigFromEnv } from '../../security/virusScan.js';
+import { applyPrefixedRateLimitHeaders } from '../rateLimit.js';
+import { createTaskforceMcpServer, isMcpWriteToolName } from '../../mcp/runtime.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { randomUUID } from 'crypto';
+import { resolveDeploymentConfig } from '../../config/deployment.js';
+import { getTaskforceCloudEnvironmentConfig, resolveTaskforceCloudEnvironmentFromBaseUrl } from '../../config/cloudEnvironment.js';
+import { resolveErrorStatusCode } from './shared.js';
+import { applyWorkspaceRepair, scanWorkspaceRepair } from '../../sync/workspaceRepair.js';
+// === SECTION: Registration ===
+export function registerAdminRoutes(deps) {
+    const { addRoute, core, context, requestWorkspaceId, requestUserId, requestRole, requestHeader, requestRuntimeMode, ensureAppAccess, ensureAdminRole, ensureCloudPlanData, requireCloudRuntime, resolveAuthenticatedUserId, resolveAdminRequestActor, auditAdminAction, resolveEffectiveObjectStorageConfig, getObjectStorageClient, taskAssetStore, normalizeDocumentPathInput, ensureWithinDir, getAssetMetadata, markAssetDeleted, clearAssetDeleted, removeAssetMetadata, getStorageTelemetry, appendStorageTelemetry, getStorageIntegrityHistory, appendStorageIntegrityHistory, getDocumentPurgeHistory, appendDocumentPurgeHistory, getCollaborationTelemetry, isCollaborationPolicyEnabled, resolveRuntimeConfigBaseUrl, resolvePublicAuthBaseUrl, parseFormBody, escapeHtml, normalizeMcpOauthScopeString, MCP_TOKEN_SCOPE_VALUES, MCP_CLOUD_TOOL_SCOPE_REQUIREMENTS, MCP_WRITE_RATE_LIMIT_ENABLED, MCP_WRITE_RATE_LIMIT_ACTOR_MAX_REQUESTS, MCP_WRITE_RATE_LIMIT_WORKSPACE_MAX_REQUESTS, MCP_WRITE_RATE_LIMIT_WINDOW_MS, } = deps;
+    const baseVirusScanConfig = resolveVirusScanConfigFromEnv(process.env);
+    const workspaceAssetStore = typeof core.getDatabaseAdapter === 'function' && typeof core.getTenantId === 'function'
+        ? new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId())
+        : null;
+    // === SECTION: Email helpers ===
+    const getEmailConfig = () => {
+        if (context.authConfig?.runtimeMode !== 'cloud') {
+            return resolveEffectiveEmailConfig(process.env, { provider: 'console' });
+        }
+        const globalSettings = core.getGlobalSettings();
+        return resolveEffectiveEmailConfig(process.env, globalSettings.email || null);
+    };
+    const getAuthBehavior = () => {
+        const globalSettings = core.getGlobalSettings();
+        const authSettings = globalSettings.auth || {};
+        const authRateLimitMaxRequestsRaw = Number(authSettings.authRateLimitMaxRequests);
+        const authRateLimitWindowMsRaw = Number(authSettings.authRateLimitWindowMs);
+        const signupSettings = core.getSignupMonetizationSettings();
+        return {
+            allowSelfRegistration: authSettings.allowSelfRegistration !== false,
+            requireVerifiedEmail: authSettings.requireVerifiedEmail !== false,
+            defaultNewUserBetaAccess: authSettings.defaultNewUserBetaAccess === true,
+            authRateLimitEnabled: authSettings.authRateLimitEnabled !== false,
+            authRateLimitMaxRequests: Number.isFinite(authRateLimitMaxRequestsRaw) && authRateLimitMaxRequestsRaw >= 1
+                ? Math.floor(authRateLimitMaxRequestsRaw)
+                : 10,
+            authRateLimitWindowMs: Number.isFinite(authRateLimitWindowMsRaw) && authRateLimitWindowMsRaw >= 1000
+                ? Math.floor(authRateLimitWindowMsRaw)
+                : 15 * 60_000,
+            signupMonetizationStrategy: signupSettings.strategy,
+            defaultSignupPlanVersionId: signupSettings.defaultSignupPlanVersionId
+        };
+    };
+    const getSiteBehavior = () => {
+        const globalSettings = core.getGlobalSettings();
+        const siteSettings = globalSettings.site || {};
+        return {
+            showRunTaskforceLocally: siteSettings.showRunTaskforceLocally !== false,
+            pricingPageEnabled: siteSettings.pricingPageEnabled !== false
+        };
+    };
+    const resolveEffectiveVirusScanSettings = () => {
+        const settings = core.getGlobalSettings().objectStorage || {};
+        const asyncEnabled = typeof settings.virusScanAsyncEnabled === 'boolean'
+            ? settings.virusScanAsyncEnabled
+            : String(process.env.TASKFORCE_VIRUS_SCAN_ASYNC || 'true').trim().toLowerCase() !== 'false';
+        const failClosed = typeof settings.virusScanFailClosed === 'boolean'
+            ? settings.virusScanFailClosed
+            : baseVirusScanConfig.failClosed;
+        return {
+            asyncEnabled: Boolean(taskAssetStore) && asyncEnabled,
+            failClosed
+        };
+    };
+    // === SECTION: MCP helpers ===
+    const writeMcpHttpError = (res, statusCode, message) => {
+        res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            jsonrpc: '2.0',
+            error: { code: -32000, message },
+            id: null,
+        }));
+    };
+    const resolveMcpOauthIssuer = (req) => {
+        const runtimeBaseUrl = resolveRuntimeConfigBaseUrl(req);
+        if (runtimeBaseUrl)
+            return runtimeBaseUrl;
+        return resolveDeploymentConfig(process.env).cloudMcpBaseUrl || resolvePublicAuthBaseUrl(req);
+    };
+    const resolveCloudLoginBaseUrl = (req) => {
+        const requestBaseUrl = resolveRuntimeConfigBaseUrl(req);
+        const deployment = resolveDeploymentConfig(process.env, { requestBaseUrl });
+        const configured = String(deployment.cloudAuthBaseUrl || deployment.cloudBaseUrl || '').replace(/\/+$/, '');
+        const inferredEnvironment = resolveTaskforceCloudEnvironmentFromBaseUrl(configured || requestBaseUrl);
+        if (inferredEnvironment) {
+            return getTaskforceCloudEnvironmentConfig(inferredEnvironment).appBaseUrl.replace(/\/+$/, '');
+        }
+        return String(configured || resolvePublicAuthBaseUrl(req)).replace(/\/+$/, '');
+    };
+    const resolveMcpOauthAuthorizeUrl = (req) => `${resolveMcpOauthIssuer(req)}/oauth/mcp/authorize`;
+    const resolveMcpOauthTokenUrl = (req) => `${resolveMcpOauthIssuer(req)}/oauth/mcp/token`;
+    const resolveMcpOauthRegisterUrl = (req) => `${resolveMcpOauthIssuer(req)}/oauth/mcp/register`;
+    const resolveMcpOauthResourceUrl = (req) => `${resolveMcpOauthIssuer(req)}/mcp`;
+    const renderMcpOauthAuthorizePage = (input) => {
+        const options = input.workspaces.map((workspace) => {
+            const selected = workspace.id === input.preselectedWorkspaceId ? ' selected' : '';
+            return `<option value="${escapeHtml(workspace.id)}"${selected}>${escapeHtml(workspace.name)} (${escapeHtml(workspace.role)})</option>`;
+        }).join('');
+        const scopeBadges = input.scopes.map((scope) => `<span style="display:inline-flex;padding:6px 10px;border-radius:999px;background:#272742;border:1px solid rgba(255,255,255,0.09);font-size:12px;">${escapeHtml(scope)}</span>`).join('');
+        const termsUrl = 'https://taskforcehq.com/legal/terms';
+        const privacyUrl = 'https://taskforcehq.com/legal/privacy';
+        return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Authorize Taskforce MCP Connector</title>
+  <style>
+    :root { color-scheme: dark; }
+    body { margin: 0; font-family: Inter, system-ui, sans-serif; background: #111126; color: #f8f7ff; }
+    .wrap { min-height: 100vh; display: flex; align-items: center; justify-content: center; padding: 24px; }
+    .card { width: min(560px, 100%); background: rgba(22,22,44,0.95); border: 1px solid rgba(255,255,255,0.08); border-radius: 20px; box-shadow: 0 20px 80px rgba(0,0,0,0.35); padding: 28px; }
+    h1 { margin: 0 0 8px; font-size: 24px; }
+    p { margin: 0 0 16px; color: rgba(255,255,255,0.72); line-height: 1.45; }
+    label { display: block; font-size: 13px; font-weight: 600; margin: 18px 0 8px; color: rgba(255,255,255,0.9); }
+    select { width: 100%; border-radius: 14px; border: 1px solid rgba(255,255,255,0.1); background: #1a1a34; color: #fff; padding: 12px 14px; font-size: 14px; }
+    .scopes { display:flex; flex-wrap:wrap; gap:8px; margin-top:8px; }
+    .meta { margin-top: 18px; padding: 14px 16px; border-radius: 14px; background: rgba(255,255,255,0.04); border: 1px solid rgba(255,255,255,0.08); }
+    .meta p { margin: 10px 0 0; font-size: 13px; color: rgba(255,255,255,0.68); }
+    .error { margin-bottom: 16px; padding: 12px 14px; border-radius: 12px; background: rgba(255,99,132,0.12); color: #ffb6c6; border: 1px solid rgba(255,99,132,0.25); }
+    .actions { display:flex; justify-content:flex-end; gap:12px; margin-top: 24px; }
+    button { border-radius: 12px; padding: 11px 16px; font-size: 14px; font-weight: 600; cursor: pointer; border: 1px solid rgba(255,255,255,0.08); }
+    button[name="decision"][value="deny"] { background: transparent; color: rgba(255,255,255,0.85); }
+    button[name="decision"][value="approve"] { background: #8d6bff; color: white; border-color: rgba(141,107,255,0.6); }
+    a { color: #b9d6ff; }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <form class="card" method="post" action="/oauth/mcp/authorize">
+      <h1>Authorize Taskforce Connector</h1>
+      <p>${escapeHtml(input.clientName)} wants access to Taskforce MCP for ${escapeHtml(input.userName)}.</p>
+      ${input.error ? `<div class="error">${escapeHtml(input.error)}</div>` : ''}
+      <label for="workspaceId">Workspace</label>
+      <select id="workspaceId" name="workspaceId" required>${options}</select>
+      <label>Requested Scopes</label>
+      <div class="scopes">${scopeBadges}</div>
+      <div class="meta">
+        <div><strong>Client:</strong> ${escapeHtml(input.clientName)}</div>
+        <div><strong>Redirect URI:</strong> ${escapeHtml(input.redirectUri)}</div>
+        <p>By authorizing this connector, you agree to Taskforce&apos;s <a href="${termsUrl}" target="_blank" rel="noopener noreferrer">Terms of Service</a> and acknowledge the <a href="${privacyUrl}" target="_blank" rel="noopener noreferrer">Privacy Policy</a>.</p>
+      </div>
+      <input type="hidden" name="client_id" value="${escapeHtml(input.clientId)}" />
+      <input type="hidden" name="redirect_uri" value="${escapeHtml(input.redirectUri)}" />
+      <input type="hidden" name="scope" value="${escapeHtml(input.scopes.join(' '))}" />
+      <input type="hidden" name="state" value="${escapeHtml(input.state)}" />
+      <input type="hidden" name="code_challenge" value="${escapeHtml(input.codeChallenge)}" />
+      <input type="hidden" name="code_challenge_method" value="${escapeHtml(input.codeChallengeMethod)}" />
+      <div class="actions">
+        <button type="submit" name="decision" value="deny">Cancel</button>
+        <button type="submit" name="decision" value="approve">Authorize</button>
+      </div>
+    </form>
+  </div>
+</body>
+</html>`;
+    };
+    const extractMcpWriteToolNames = (body) => {
+        const messages = Array.isArray(body) ? body : [body];
+        const names = messages.flatMap((message) => {
+            if (!message || typeof message !== 'object')
+                return [];
+            const method = String(message.method || '').trim();
+            if (method !== 'tools/call')
+                return [];
+            const toolName = String(message?.params?.name || '').trim();
+            return toolName && isMcpWriteToolName(toolName) ? [toolName] : [];
+        });
+        return Array.from(new Set(names));
+    };
+    const extractFirstMcpToolName = (body) => {
+        const messages = Array.isArray(body) ? body : [body];
+        for (const message of messages) {
+            if (!message || typeof message !== 'object')
+                continue;
+            if (String(message.method || '').trim() !== 'tools/call')
+                continue;
+            const toolName = String(message?.params?.name || '').trim();
+            if (toolName)
+                return toolName;
+        }
+        return null;
+    };
+    const findDeniedCloudMcpToolName = (body, scopes) => {
+        const messages = Array.isArray(body) ? body : [body];
+        for (const message of messages) {
+            if (!message || typeof message !== 'object')
+                continue;
+            if (String(message.method || '').trim() !== 'tools/call')
+                continue;
+            const toolName = String(message?.params?.name || '').trim();
+            if (!toolName)
+                continue;
+            const requiredScope = MCP_CLOUD_TOOL_SCOPE_REQUIREMENTS[toolName];
+            if (!requiredScope || !scopes.includes(requiredScope))
+                return toolName;
+        }
+        return null;
+    };
+    const authenticateCloudMcpRequest = (req, res) => {
+        const authorization = requestHeader(req, 'authorization', '').trim();
+        const bearerToken = authorization.toLowerCase().startsWith('bearer ')
+            ? authorization.slice(7).trim()
+            : '';
+        const requestedWorkspaceId = requestHeader(req, 'x-taskforce-workspace-id', '').trim();
+        const aiProfileToken = requestHeader(req, 'x-taskforce-ai-profile-token', '').trim() || null;
+        const aiProfileName = requestHeader(req, 'x-taskforce-ai-name', '').trim() || null;
+        const aiProfileDescription = requestHeader(req, 'x-taskforce-ai-description', '').trim() || null;
+        const aiProfileRole = requestHeader(req, 'x-taskforce-ai-role', '').trim() || null;
+        const aiProfileProvider = requestHeader(req, 'x-taskforce-ai-provider', '').trim() || null;
+        const aiProfileModel = requestHeader(req, 'x-taskforce-ai-model', '').trim() || null;
+        const aiProfileSurfaceType = requestHeader(req, 'x-taskforce-ai-surface-type', '').trim() || null;
+        if (bearerToken) {
+            const tokenAuth = core.authenticateMcpAccessToken(bearerToken);
+            const oauthAuth = tokenAuth ? null : core.authenticateMcpOAuthAccessToken(bearerToken);
+            if ((!tokenAuth || tokenAuth.status !== 'active') && (!oauthAuth || oauthAuth.status !== 'active')) {
+                core.addMcpAuditLog({
+                    workspaceId: requestedWorkspaceId || 'default',
+                    actorType: 'token',
+                    actorUserId: 'anonymous',
+                    toolName: 'auth',
+                    details: {
+                        requestId: String(req.headers['x-request-id'] || req.headers['x-railway-request-id'] || '').trim() || randomUUID(),
+                        ip: req.socket?.remoteAddress || null,
+                        userAgent: requestHeader(req, 'user-agent', '') || null,
+                        outcome: 'deny',
+                        reasonCode: 'invalid_credential',
+                        workspaceIdHint: requestedWorkspaceId || null
+                    }
+                });
+                writeMcpHttpError(res, 401, 'Unauthorized.');
+                return null;
+            }
+            const resolvedWorkspaceId = tokenAuth?.workspaceId || oauthAuth?.workspaceId || '';
+            if (requestedWorkspaceId && requestedWorkspaceId !== resolvedWorkspaceId) {
+                core.addMcpAuditLog({
+                    workspaceId: resolvedWorkspaceId || requestedWorkspaceId || 'default',
+                    actorType: tokenAuth ? 'token' : 'oauth',
+                    actorUserId: tokenAuth?.userId || oauthAuth?.userId || 'anonymous',
+                    tokenId: tokenAuth?.tokenId || oauthAuth?.grantId || null,
+                    toolName: 'auth',
+                    details: {
+                        requestId: String(req.headers['x-request-id'] || req.headers['x-railway-request-id'] || '').trim() || randomUUID(),
+                        ip: req.socket?.remoteAddress || null,
+                        userAgent: requestHeader(req, 'user-agent', '') || null,
+                        outcome: 'deny',
+                        reasonCode: 'workspace_mismatch',
+                        requestedWorkspaceId,
+                        credentialWorkspaceId: resolvedWorkspaceId
+                    }
+                });
+                writeMcpHttpError(res, 403, 'Forbidden.');
+                return null;
+            }
+            return {
+                workspaceId: resolvedWorkspaceId,
+                authenticatedViaToken: tokenAuth || null,
+                authenticatedViaOAuth: oauthAuth || null,
+                userId: null,
+                aiProfileToken,
+                aiProfileName,
+                aiProfileDescription,
+                aiProfileRole,
+                aiProfileProvider,
+                aiProfileModel,
+                aiProfileSurfaceType,
+            };
+        }
+        core.addMcpAuditLog({
+            workspaceId: requestedWorkspaceId || 'default',
+            actorType: 'user',
+            actorUserId: resolveAuthenticatedUserId(req) || 'anonymous',
+            toolName: 'auth',
+            details: {
+                requestId: String(req.headers['x-request-id'] || req.headers['x-railway-request-id'] || '').trim() || randomUUID(),
+                ip: req.socket?.remoteAddress || null,
+                userAgent: requestHeader(req, 'user-agent', '') || null,
+                outcome: 'deny',
+                reasonCode: 'missing_bearer'
+            }
+        });
+        writeMcpHttpError(res, 401, 'Unauthorized.');
+        return null;
+    };
+    const recordCloudMcpCredentialUsage = (req, tokenAuth, oauthAuth) => {
+        if (tokenAuth) {
+            core.recordMcpAccessTokenUsage({
+                tokenId: tokenAuth.tokenId,
+                workspaceId: tokenAuth.workspaceId,
+                ip: req.socket?.remoteAddress || null,
+                userAgent: requestHeader(req, 'user-agent', '') || null,
+            });
+            return;
+        }
+        if (oauthAuth) {
+            core.recordMcpOAuthConnectorGrantUsage({
+                grantId: oauthAuth.grantId,
+                workspaceId: oauthAuth.workspaceId,
+            });
+        }
+    };
+    const applyCloudMcpWriteRateLimit = (req, res, auth, body) => {
+        if (!MCP_WRITE_RATE_LIMIT_ENABLED)
+            return true;
+        const writeTools = extractMcpWriteToolNames(body);
+        if (writeTools.length === 0)
+            return true;
+        const actorKey = auth.authenticatedViaToken?.tokenId
+            ? `token:${auth.authenticatedViaToken.tokenId}`
+            : auth.authenticatedViaOAuth?.grantId
+                ? `oauth:${auth.authenticatedViaOAuth.grantId}`
+                : auth.userId
+                    ? `user:${auth.userId}`
+                    : `workspace:${auth.workspaceId}`;
+        const actorResult = core.checkMcpRateLimit({
+            scope: 'actor',
+            key: actorKey,
+            limit: MCP_WRITE_RATE_LIMIT_ACTOR_MAX_REQUESTS,
+            windowMs: MCP_WRITE_RATE_LIMIT_WINDOW_MS
+        });
+        const workspaceResult = core.checkMcpRateLimit({
+            scope: 'workspace',
+            key: auth.workspaceId,
+            limit: MCP_WRITE_RATE_LIMIT_WORKSPACE_MAX_REQUESTS,
+            windowMs: MCP_WRITE_RATE_LIMIT_WINDOW_MS
+        });
+        applyPrefixedRateLimitHeaders(res, actorResult, 'X-MCP-Write-RateLimit');
+        applyPrefixedRateLimitHeaders(res, workspaceResult, 'X-MCP-Write-Workspace-RateLimit');
+        if (actorResult.allowed && workspaceResult.allowed)
+            return true;
+        const retryAfterSeconds = Math.max(actorResult.retryAfterSeconds, workspaceResult.retryAfterSeconds);
+        res.setHeader('Retry-After', String(retryAfterSeconds));
+        core.addMcpAuditLog({
+            workspaceId: auth.workspaceId,
+            actorType: auth.authenticatedViaToken ? 'token' : auth.authenticatedViaOAuth ? 'oauth' : 'user',
+            actorUserId: auth.authenticatedViaToken?.userId || auth.authenticatedViaOAuth?.userId || auth.userId || 'anonymous',
+            tokenId: auth.authenticatedViaToken?.tokenId || auth.authenticatedViaOAuth?.grantId || null,
+            toolName: extractFirstMcpToolName(body) || 'rate_limit',
+            details: {
+                requestId: String(req.headers['x-request-id'] || req.headers['x-railway-request-id'] || '').trim() || randomUUID(),
+                ip: req.socket?.remoteAddress || null,
+                userAgent: requestHeader(req, 'user-agent', '') || null,
+                outcome: 'deny',
+                reasonCode: actorResult.allowed ? 'workspace_write_rate_limited' : 'actor_write_rate_limited',
+                actorLimit: actorResult.limit,
+                workspaceLimit: workspaceResult.limit
+            }
+        });
+        writeMcpHttpError(res, 429, 'Write rate limit exceeded. Retry later.');
+        return false;
+    };
+    const handleCloudMcpRequest = async (req, res) => {
+        if (requestRuntimeMode(req) !== 'cloud') {
+            writeMcpHttpError(res, 400, 'The /mcp HTTP endpoint is only available in cloud runtime. In local runtime, use the local stdio MCP server (for example: `taskforce mcp <project-path>`).');
+            return;
+        }
+        if (!ensureAppAccess(req, res))
+            return;
+        if (req.method !== 'POST' && req.method !== 'GET' && req.method !== 'DELETE') {
+            writeMcpHttpError(res, 405, 'Method not allowed.');
+            return;
+        }
+        const auth = authenticateCloudMcpRequest(req, res);
+        if (!auth)
+            return;
+        if (req.method !== 'POST') {
+            writeMcpHttpError(res, 405, 'Method not allowed.');
+            return;
+        }
+        let body = undefined;
+        try {
+            body = await parseJsonBody(req);
+        }
+        catch (error) {
+            writeMcpHttpError(res, resolveErrorStatusCode(error, 400), 'Invalid JSON body.');
+            return;
+        }
+        const authScopes = auth.authenticatedViaToken?.scopes || auth.authenticatedViaOAuth?.scopes || [];
+        const deniedToolName = findDeniedCloudMcpToolName(body, authScopes);
+        if (deniedToolName) {
+            core.addMcpAuditLog({
+                workspaceId: auth.workspaceId,
+                actorType: auth.authenticatedViaToken ? 'token' : auth.authenticatedViaOAuth ? 'oauth' : 'user',
+                actorUserId: auth.authenticatedViaToken?.userId || auth.authenticatedViaOAuth?.userId || auth.userId || 'anonymous',
+                tokenId: auth.authenticatedViaToken?.tokenId || auth.authenticatedViaOAuth?.grantId || null,
+                toolName: deniedToolName,
+                details: {
+                    requestId: String(req.headers['x-request-id'] || req.headers['x-railway-request-id'] || '').trim() || randomUUID(),
+                    ip: req.socket?.remoteAddress || null,
+                    userAgent: requestHeader(req, 'user-agent', '') || null,
+                    outcome: 'deny',
+                    reasonCode: 'scope_denied',
+                    scopes: authScopes
+                }
+            });
+            writeMcpHttpError(res, 403, 'Forbidden.');
+            return;
+        }
+        if (!applyCloudMcpWriteRateLimit(req, res, auth, body))
+            return;
+        try {
+            const runtime = createTaskforceMcpServer({
+                projectRoot: core.getPaths().projectRoot,
+                tenantId: core.getTenantId(),
+                workspaceId: auth.workspaceId,
+                serverName: 'taskforce-cloud',
+                logStartup: false,
+                runtimeMode: 'cloud',
+                auth: {
+                    scopes: authScopes,
+                    userId: auth.authenticatedViaToken?.userId || auth.authenticatedViaOAuth?.userId || auth.userId || null,
+                    tokenId: auth.authenticatedViaToken?.tokenId || auth.authenticatedViaOAuth?.grantId || null,
+                    aiProfileToken: auth.aiProfileToken,
+                    aiProfileName: auth.aiProfileName,
+                    aiProfileDescription: auth.aiProfileDescription,
+                    aiProfileRole: auth.aiProfileRole,
+                    aiProfileProvider: auth.aiProfileProvider,
+                    aiProfileModel: auth.aiProfileModel,
+                    aiProfileSurfaceType: auth.aiProfileSurfaceType,
+                    actorType: auth.authenticatedViaToken ? 'token' : auth.authenticatedViaOAuth ? 'oauth' : 'user',
+                    requestId: String(req.headers['x-request-id'] || req.headers['x-railway-request-id'] || '').trim() || randomUUID(),
+                    ip: req.socket?.remoteAddress || null,
+                    userAgent: requestHeader(req, 'user-agent', '') || null,
+                },
+            });
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+            });
+            await runtime.server.connect(transport);
+            if (!isInitializeRequest(body)) {
+                // Stateless cloud sessions still require a valid MCP JSON-RPC request;
+                // let the SDK validate and respond rather than trying to track sessions server-side.
+            }
+            await transport.handleRequest(req, res, body);
+            recordCloudMcpCredentialUsage(req, auth.authenticatedViaToken, auth.authenticatedViaOAuth);
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                writeMcpHttpError(res, 500, 'Internal server error.');
+            }
+        }
+    };
+    // === SECTION: Platform plan management ===
+    addRoute('GET', '/api/platform/plans', async (req, res) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const plans = core.listPlanCatalog();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, plans }));
+    });
+    addRoute('POST', '/api/platform/plans', async (req, res) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        try {
+            const plan = core.upsertPlanCatalog({
+                planId: body?.planId,
+                displayName: body?.displayName,
+                status: body?.status,
+                initialMode: body?.initialMode,
+                initialTrialDays: body?.initialTrialDays === undefined ? undefined : Number(body?.initialTrialDays),
+                initialSeatLimit: body?.initialSeatLimit === null
+                    ? null
+                    : (body?.initialSeatLimit === undefined ? undefined : Number(body?.initialSeatLimit))
+            });
+            auditAdminAction(req, 'platform-plan-upsert', { planId: plan.planId, status: plan.status });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, plan }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to upsert plan'), code: error?.code }));
+        }
+    });
+    addRoute('GET', '/api/platform/plans/:planId/versions', async (req, res, params) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        try {
+            const versions = core.listPlanVersions(params.planId);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, versions }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to list plan versions'), code: error?.code }));
+        }
+    });
+    addRoute('GET', '/api/platform/features', async (req, res) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        try {
+            const features = core.listPlanFeatureCatalog();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, features }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to list feature catalog'), code: error?.code }));
+        }
+    });
+    addRoute('POST', '/api/platform/plans/:planId/versions', async (req, res, params) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        try {
+            const versionNumber = Math.max(1, Math.floor(Number(body?.versionNumber || 1)));
+            const isDefault = body?.isDefault === true;
+            const planVersionId = `${params.planId}-v${versionNumber}`;
+            if (isDefault) {
+                try {
+                    const db = core.getDatabaseAdapter();
+                    const tenantId = core.getTenantId();
+                    const mappingCountRow = db.prepare(`
+                        SELECT COUNT(*) AS count
+                        FROM billing_price_mappings
+                        WHERE tenant_id = ?
+                          AND plan_version_id = ?
+                          AND active = 1
+                          AND billing_interval IN ('month', 'year')
+                    `).get(tenantId, planVersionId);
+                    const mappingCount = Number(mappingCountRow?.count || 0);
+                    if (mappingCount < 1) {
+                        res.writeHead(409, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({
+                            success: false,
+                            error: 'Default version requires at least one active price mapping (month or year).',
+                            code: 'PLAN_VERSION_PRICING_REQUIRED'
+                        }));
+                        return;
+                    }
+                }
+                catch {
+                    // If billing mapping storage is unavailable in this runtime, skip default guardrail check.
+                }
+            }
+            let version;
+            try {
+                version = core.updatePlanVersion({
+                    planId: params.planId,
+                    versionNumber,
+                    isDefault,
+                    seatLimit: body?.seatLimit === null ? null : (body?.seatLimit === undefined ? undefined : Number(body?.seatLimit)),
+                    trialDays: body?.trialDays === undefined ? undefined : Number(body?.trialDays),
+                    metadata: body?.metadata && typeof body.metadata === 'object' ? body.metadata : {}
+                });
+            }
+            catch (error) {
+                if (error?.code === 'PLAN_VERSION_NOT_FOUND') {
+                    version = core.createPlanVersion({
+                        planId: params.planId,
+                        versionNumber,
+                        isDefault,
+                        seatLimit: body?.seatLimit === null ? null : (body?.seatLimit === undefined ? undefined : Number(body?.seatLimit)),
+                        trialDays: body?.trialDays === undefined ? undefined : Number(body?.trialDays),
+                        metadata: body?.metadata && typeof body.metadata === 'object' ? body.metadata : {}
+                    });
+                }
+                else {
+                    throw error;
+                }
+            }
+            auditAdminAction(req, 'platform-plan-version-upsert', { planId: params.planId, planVersionId: version.planVersionId });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, version }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to upsert plan version'), code: error?.code }));
+        }
+    });
+    addRoute('GET', '/api/platform/plans/:planId/versions/:versionId/features', async (req, res, params) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        try {
+            const version = core.getPlanVersionFeatures(params.planId, params.versionId);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, version }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to read plan features'), code: error?.code }));
+        }
+    });
+    addRoute('PATCH', '/api/platform/plans/:planId/versions/:versionId/features', async (req, res, params) => {
+        if (!ensureCloudPlanData(req, res))
+            return;
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const features = Array.isArray(body?.features) ? body.features : [];
+        try {
+            const version = core.updatePlanVersionFeatures({
+                planVersionId: params.versionId,
+                features: features.map((feature) => ({
+                    featureKey: String(feature?.featureKey || ''),
+                    access: String(feature?.access || 'disabled'),
+                    config: feature?.config && typeof feature.config === 'object' ? feature.config : {}
+                }))
+            });
+            auditAdminAction(req, 'platform-plan-features-updated', {
+                planId: params.planId,
+                planVersionId: params.versionId,
+                featureCount: features.length
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, version }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to update plan features'), code: error?.code }));
+        }
+    });
+    addRoute('GET', '/api/platform/accounts/:accountId/entitlement', async (req, res, params) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        try {
+            const entitlement = core.getAccountEntitlement(params.accountId);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, entitlement }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to read entitlement'), code: error?.code }));
+        }
+    });
+    addRoute('PATCH', '/api/platform/accounts/:accountId/entitlement', async (req, res, params) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const actor = resolveAdminRequestActor(req);
+        try {
+            const entitlement = core.updateAccountEntitlement({
+                accountId: params.accountId,
+                planVersionId: body?.planVersionId,
+                entitlementState: body?.state,
+                effectiveAt: body?.effectiveAt ?? undefined,
+                effectiveUntil: body?.effectiveUntil ?? undefined,
+                actorUserId: actor.userId,
+                actorRole: actor.systemRole,
+                reason: typeof body?.reason === 'string' ? body.reason : undefined,
+                requestId: String(req.headers['x-request-id'] || '').trim() || undefined
+            });
+            auditAdminAction(req, 'platform-account-entitlement-updated', {
+                accountId: params.accountId,
+                planVersionId: entitlement.planVersionId,
+                state: entitlement.state
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, entitlement }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to update entitlement'), code: error?.code }));
+        }
+    });
+    addRoute('GET', '/api/platform/accounts/:accountId/entitlement-history', async (req, res, params) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const reqUrl = new URL(req.url || '/api/platform/accounts/:accountId/entitlement-history', 'http://localhost');
+        const limitRaw = Number(reqUrl.searchParams.get('limit') || '100');
+        const offsetRaw = Number(reqUrl.searchParams.get('offset') || '0');
+        const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.min(500, Math.floor(limitRaw))) : 100;
+        const offset = Number.isFinite(offsetRaw) ? Math.max(0, Math.floor(offsetRaw)) : 0;
+        const events = core.listEntitlementAuditLog(params.accountId, limit, offset);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, events, limit, offset }));
+    });
+    addRoute('GET', '/api/platform/accounts/search', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const reqUrl = new URL(req.url || '/api/platform/accounts/search', 'http://localhost');
+        const query = String(reqUrl.searchParams.get('q') || '').trim();
+        const limitRaw = Number(reqUrl.searchParams.get('limit') || '20');
+        const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.min(100, Math.floor(limitRaw))) : 20;
+        const accounts = core.searchAccountsByEmail(query, limit);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, accounts }));
+    });
+    // === SECTION: System admin user management ===
+    // GET /api/taskforce/admin/system-users - List users with global system roles
+    addRoute('GET', '/api/taskforce/admin/system-users', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const users = core.listSystemUsers();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ users }));
+    });
+    // GET /api/taskforce/admin/audit-logs - Read recent admin audit events
+    addRoute('GET', '/api/taskforce/admin/audit-logs', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const workspaceId = 'system';
+        const reqUrl = new URL(req.url || '/api/taskforce/admin/audit-logs', 'http://localhost');
+        const limitRaw = Number(reqUrl.searchParams.get('limit') || '100');
+        const offsetRaw = Number(reqUrl.searchParams.get('offset') || '0');
+        const from = String(reqUrl.searchParams.get('from') || '').trim();
+        const to = String(reqUrl.searchParams.get('to') || '').trim();
+        const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.min(500, Math.floor(limitRaw))) : 100;
+        const offset = Number.isFinite(offsetRaw) ? Math.max(0, Math.floor(offsetRaw)) : 0;
+        const filters = { from, to };
+        const events = core.listAdminAuditLogs(workspaceId, limit, offset, filters).map((event) => ({
+            id: event.id,
+            action: event.action,
+            actorUserId: event.actorUserId,
+            actorRole: event.actorRole,
+            workspaceId: event.workspaceId,
+            details: event.details,
+            createdAt: event.ts
+        }));
+        const total = core.countAdminAuditLogs(workspaceId, filters);
+        const page = Math.floor(offset / limit) + 1;
+        const pages = Math.max(1, Math.ceil(total / limit));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ events, limit, offset, total, page, pages, from: from || null, to: to || null }));
+    });
+    // GET /api/taskforce/admin/mcp-audit-logs - Read recent MCP audit events
+    addRoute('GET', '/api/taskforce/admin/mcp-audit-logs', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const reqUrl = new URL(req.url || '/api/taskforce/admin/mcp-audit-logs', 'http://localhost');
+        const limitRaw = Number(reqUrl.searchParams.get('limit') || '100');
+        const offsetRaw = Number(reqUrl.searchParams.get('offset') || '0');
+        const from = String(reqUrl.searchParams.get('from') || '').trim();
+        const to = String(reqUrl.searchParams.get('to') || '').trim();
+        const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.min(500, Math.floor(limitRaw))) : 100;
+        const offset = Number.isFinite(offsetRaw) ? Math.max(0, Math.floor(offsetRaw)) : 0;
+        const filters = { from, to };
+        const events = core.listMcpAuditLogs(limit, offset, filters).map((event) => ({
+            id: event.id,
+            workspaceId: event.workspaceId,
+            actorType: event.actorType,
+            actorUserId: event.actorUserId,
+            tokenId: event.tokenId,
+            toolName: event.toolName,
+            requestId: event.requestId,
+            ip: event.ip,
+            userAgent: event.userAgent,
+            outcome: event.outcome,
+            reasonCode: event.reasonCode,
+            details: event.details,
+            createdAt: event.ts
+        }));
+        const total = core.countMcpAuditLogs(filters);
+        const page = Math.floor(offset / limit) + 1;
+        const pages = Math.max(1, Math.ceil(total / limit));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ events, limit, offset, total, page, pages, from: from || null, to: to || null }));
+    });
+    // PATCH /api/taskforce/admin/system-users/:id/role - Update global system role
+    addRoute('PATCH', '/api/taskforce/admin/system-users/:id/role', async (req, res, params) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const role = String(body?.systemRole || '').trim();
+        if (role !== 'system_admin' && role !== 'user') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'systemRole must be system_admin or user' }));
+            return;
+        }
+        try {
+            const success = core.setSystemRole(params.id, role);
+            if (!success) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'User not found' }));
+                return;
+            }
+            auditAdminAction(req, 'update-system-role', { targetUserId: params.id, systemRole: role });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to update system role'), code: error?.code }));
+        }
+    });
+    // GET /api/taskforce/admin/collaboration-telemetry - Read collaboration rollout telemetry counters
+    addRoute('GET', '/api/taskforce/admin/collaboration-telemetry', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const telemetry = getCollaborationTelemetry();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            policyEnabled: isCollaborationPolicyEnabled(),
+            telemetry
+        }));
+    });
+    // PATCH /api/taskforce/admin/system-users/:id/disable - Enable/disable a user globally
+    addRoute('PATCH', '/api/taskforce/admin/system-users/:id/disable', async (req, res, params) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const disabled = Boolean(body?.disabled);
+        try {
+            const success = core.setUserDisabledGlobal(params.id, disabled);
+            if (!success) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'User not found' }));
+                return;
+            }
+            auditAdminAction(req, 'set-user-disabled-global', { targetUserId: params.id, disabled });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to update user disabled state'), code: error?.code }));
+        }
+    });
+    // PATCH /api/taskforce/admin/system-users/:id/beta-access - Enable/disable global beta access
+    addRoute('PATCH', '/api/taskforce/admin/system-users/:id/beta-access', async (req, res, params) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const enabled = body?.enabled !== false;
+        const success = core.setUserBetaAccessGlobal(params.id, enabled);
+        if (!success) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'User not found' }));
+            return;
+        }
+        auditAdminAction(req, 'set-user-beta-access-global', { targetUserId: params.id, enabled });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    });
+    // === SECTION: Admin email settings ===
+    // GET /api/taskforce/admin/email-settings - Read email provider settings
+    addRoute('GET', '/api/taskforce/admin/email-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        if (context.authConfig?.runtimeMode !== 'cloud') {
+            const effective = getEmailConfig();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                settings: { provider: 'console', from: effective.from, replyTo: '' },
+                status: { effectiveProvider: 'console', hasProviderApiKey: false, hasStoredProviderApiKey: false }
+            }));
+            return;
+        }
+        const settings = core.getGlobalSettings().email || {};
+        const effective = getEmailConfig();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            settings: {
+                provider: settings.provider || effective.provider,
+                from: settings.from || effective.from,
+                replyTo: settings.replyTo || effective.replyTo || ''
+            },
+            status: {
+                effectiveProvider: effective.provider,
+                hasProviderApiKey: effective.provider === 'resend' || effective.provider === 'google-workspace'
+                    ? Boolean(effective.providerApiKey)
+                    : true,
+                hasStoredProviderApiKey: typeof settings.providerApiKey === 'string' && settings.providerApiKey.trim().length > 0
+            }
+        }));
+    });
+    // GET /api/taskforce/admin/email-settings/health - Delivery readiness snapshot
+    addRoute('GET', '/api/taskforce/admin/email-settings/health', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const settings = core.getGlobalSettings().email || {};
+        const effective = getEmailConfig();
+        const keyRequired = effective.provider === 'resend' || effective.provider === 'google-workspace';
+        const ready = keyRequired ? Boolean(effective.providerApiKey) : true;
+        const reason = ready
+            ? null
+            : effective.provider === 'google-workspace'
+                ? 'Missing Google app password.'
+                : 'Missing provider API key.';
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            health: {
+                provider: effective.provider,
+                from: effective.from,
+                replyTo: effective.replyTo || '',
+                ready,
+                reason,
+                hasStoredProviderApiKey: typeof settings.providerApiKey === 'string' && settings.providerApiKey.trim().length > 0,
+                hasEffectiveProviderApiKey: Boolean(effective.providerApiKey)
+            }
+        }));
+    });
+    // GET /api/taskforce/admin/system-settings - Read auth/system behavior settings
+    addRoute('GET', '/api/taskforce/admin/system-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const authSettings = core.getGlobalSettings().auth || {};
+        const effective = getAuthBehavior();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            settings: {
+                ...(typeof authSettings.allowSelfRegistration === 'boolean' ? { allowSelfRegistration: authSettings.allowSelfRegistration } : {}),
+                ...(typeof authSettings.requireVerifiedEmail === 'boolean' ? { requireVerifiedEmail: authSettings.requireVerifiedEmail } : {}),
+                ...(typeof authSettings.defaultNewUserBetaAccess === 'boolean' ? { defaultNewUserBetaAccess: authSettings.defaultNewUserBetaAccess } : {}),
+                ...(typeof authSettings.authRateLimitEnabled === 'boolean' ? { authRateLimitEnabled: authSettings.authRateLimitEnabled } : {}),
+                ...(typeof authSettings.authRateLimitMaxRequests === 'number' ? { authRateLimitMaxRequests: authSettings.authRateLimitMaxRequests } : {}),
+                ...(typeof authSettings.authRateLimitWindowMs === 'number' ? { authRateLimitWindowMs: authSettings.authRateLimitWindowMs } : {}),
+                ...((authSettings.signupMonetizationStrategy === 'auto_assign_default' || authSettings.signupMonetizationStrategy === 'plan_selection_required')
+                    ? { signupMonetizationStrategy: authSettings.signupMonetizationStrategy }
+                    : {}),
+                ...(typeof authSettings.defaultSignupPlanVersionId === 'string' || authSettings.defaultSignupPlanVersionId === null
+                    ? { defaultSignupPlanVersionId: authSettings.defaultSignupPlanVersionId ?? null }
+                    : {})
+            },
+            status: {
+                allowSelfRegistration: effective.allowSelfRegistration,
+                requireVerifiedEmail: effective.requireVerifiedEmail,
+                defaultNewUserBetaAccess: effective.defaultNewUserBetaAccess,
+                authRateLimitEnabled: effective.authRateLimitEnabled,
+                authRateLimitMaxRequests: effective.authRateLimitMaxRequests,
+                authRateLimitWindowMs: effective.authRateLimitWindowMs,
+                signupMonetizationStrategy: effective.signupMonetizationStrategy,
+                defaultSignupPlanVersionId: effective.defaultSignupPlanVersionId
+            }
+        }));
+    });
+    const handleGetSiteSettings = async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const siteSettings = core.getGlobalSettings().site || {};
+        const siteBehavior = getSiteBehavior();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            settings: {
+                ...(typeof siteSettings.showRunTaskforceLocally === 'boolean'
+                    ? { showRunTaskforceLocally: siteSettings.showRunTaskforceLocally }
+                    : {}),
+                ...(typeof siteSettings.pricingPageEnabled === 'boolean'
+                    ? { pricingPageEnabled: siteSettings.pricingPageEnabled }
+                    : {})
+            },
+            status: {
+                showRunTaskforceLocally: siteBehavior.showRunTaskforceLocally,
+                pricingPageEnabled: siteBehavior.pricingPageEnabled
+            }
+        }));
+    };
+    addRoute('GET', '/api/taskforce/admin/site-settings', handleGetSiteSettings);
+    addRoute('GET', '/api/taskforce/admin/site_settings', handleGetSiteSettings);
+    // GET /api/taskforce/admin/object-storage-settings - Read object storage admin overrides
+    addRoute('GET', '/api/taskforce/admin/object-storage-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const settings = core.getGlobalSettings().objectStorage || {};
+        const effective = resolveEffectiveObjectStorageConfig();
+        const defaults = {
+            keyPrefix: 'taskforce',
+            signedUploadTtlSeconds: 600,
+            signedDownloadTtlSeconds: 300,
+            virusScanAsyncEnabled: true,
+            virusScanFailClosed: baseVirusScanConfig.failClosed
+        };
+        const effectiveR2 = effective.provider === 'r2' ? effective.r2 : undefined;
+        const effectiveScanSettings = resolveEffectiveVirusScanSettings();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            settings: {
+                ...(typeof settings.keyPrefix === 'string' ? { keyPrefix: settings.keyPrefix } : {}),
+                ...(typeof settings.signedUploadTtlSeconds === 'number' ? { signedUploadTtlSeconds: settings.signedUploadTtlSeconds } : {}),
+                ...(typeof settings.signedDownloadTtlSeconds === 'number' ? { signedDownloadTtlSeconds: settings.signedDownloadTtlSeconds } : {}),
+                ...(typeof settings.virusScanAsyncEnabled === 'boolean' ? { virusScanAsyncEnabled: settings.virusScanAsyncEnabled } : {}),
+                ...(typeof settings.virusScanFailClosed === 'boolean' ? { virusScanFailClosed: settings.virusScanFailClosed } : {})
+            },
+            status: {
+                provider: effective.provider,
+                keyPrefix: typeof effectiveR2?.keyPrefix === 'string' ? effectiveR2.keyPrefix : defaults.keyPrefix,
+                signedUploadTtlSeconds: typeof effectiveR2?.signedUploadTtlSeconds === 'number' ? effectiveR2.signedUploadTtlSeconds : defaults.signedUploadTtlSeconds,
+                signedDownloadTtlSeconds: typeof effectiveR2?.signedDownloadTtlSeconds === 'number' ? effectiveR2.signedDownloadTtlSeconds : defaults.signedDownloadTtlSeconds,
+                virusScanAsyncEnabled: effectiveScanSettings.asyncEnabled,
+                virusScanFailClosed: effectiveScanSettings.failClosed
+            }
+        }));
+    });
+    // GET /api/taskforce/admin/object-storage-telemetry - Read upload/scan/purge telemetry
+    addRoute('GET', '/api/taskforce/admin/object-storage-telemetry', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const telemetry = getStorageTelemetry();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, telemetry }));
+    });
+    // POST /api/taskforce/admin/object-storage-self-test - Verify effective object storage config with live read/write/delete cycle
+    addRoute('POST', '/api/taskforce/admin/object-storage-self-test', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const effective = resolveEffectiveObjectStorageConfig();
+        const objectStorageClient = getObjectStorageClient();
+        if (effective.provider !== 'r2' || !effective.r2 || !objectStorageClient) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: 'Object storage self-test requires provider=r2.',
+                status: {
+                    provider: effective.provider
+                }
+            }));
+            return;
+        }
+        const workspaceId = requestWorkspaceId(req);
+        const relativePath = `system/self-test/${workspaceId}/object-storage-self-test-${randomUUID()}.txt`;
+        const body = Buffer.from(`Taskforce object storage self-test ${new Date().toISOString()}\n`, 'utf8');
+        const steps = [];
+        const status = {
+            provider: effective.provider,
+            bucket: effective.r2.bucket,
+            endpoint: effective.r2.endpoint,
+            accountId: effective.r2.accountId,
+            keyPrefix: effective.r2.keyPrefix
+        };
+        const fail = (step, error) => {
+            steps.push({
+                step,
+                ok: false,
+                detail: String(error?.message || error || 'Unknown error')
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                failedStep: step,
+                error: String(error?.message || error || 'Unknown error'),
+                relativePath,
+                status,
+                steps
+            }));
+        };
+        try {
+            await objectStorageClient.putObject(relativePath, body, 'text/plain; charset=utf-8');
+            steps.push({ step: 'put', ok: true });
+        }
+        catch (error) {
+            fail('put', error);
+            return;
+        }
+        try {
+            const exists = await objectStorageClient.objectExists(relativePath);
+            if (!exists)
+                throw new Error('Object was not found after upload.');
+            steps.push({ step: 'head', ok: true });
+        }
+        catch (error) {
+            fail('head', error);
+            return;
+        }
+        try {
+            const object = await objectStorageClient.getObject(relativePath);
+            if (!object)
+                throw new Error('Object could not be read after upload.');
+            if (!object.body.equals(body))
+                throw new Error('Downloaded object body does not match uploaded payload.');
+            steps.push({ step: 'get', ok: true });
+        }
+        catch (error) {
+            fail('get', error);
+            return;
+        }
+        try {
+            await objectStorageClient.deleteObject(relativePath);
+            steps.push({ step: 'delete', ok: true });
+        }
+        catch (error) {
+            fail('delete', error);
+            return;
+        }
+        try {
+            const exists = await objectStorageClient.objectExists(relativePath);
+            if (exists)
+                throw new Error('Object still exists after delete.');
+            steps.push({ step: 'verify-delete', ok: true });
+        }
+        catch (error) {
+            fail('verify-delete', error);
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            relativePath,
+            status,
+            steps
+        }));
+    });
+    // GET /api/taskforce/admin/orphaned-assets - List canonical assets without active task links
+    addRoute('GET', '/api/taskforce/admin/orphaned-assets', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        if (!workspaceAssetStore) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, assets: [] }));
+            return;
+        }
+        const reqUrl = new URL(req.url || '/api/taskforce/admin/orphaned-assets', 'http://localhost');
+        const workspaceId = String(reqUrl.searchParams.get('workspaceId') || requestWorkspaceId(req) || '').trim();
+        const assets = workspaceAssetStore.listAllByWorkspace(workspaceId, {
+            includeDeleted: false
+        }).filter((asset) => workspaceAssetStore.listLinksForAsset(asset.assetId, workspaceId).every((link) => !!link.deletedAt))
+            .map((asset) => ({
+            assetId: asset.assetId,
+            workspaceId: asset.workspaceId,
+            kind: asset.kind,
+            originalFilename: asset.originalFilename,
+            storageKey: asset.storageKey,
+            storageProvider: asset.storageProvider,
+            updatedAt: asset.updatedAt,
+            sizeBytes: asset.sizeBytes,
+            documentId: asset.documentId
+        }));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, assets }));
+    });
+    // POST /api/taskforce/admin/orphaned-assets/attach - Attach an orphaned canonical asset to a task
+    addRoute('POST', '/api/taskforce/admin/orphaned-assets/attach', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        if (!workspaceAssetStore) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Workspace asset store unavailable.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const assetId = String(body?.assetId || '').trim();
+        const taskId = String(body?.taskId || '').trim();
+        const workspaceId = String(body?.workspaceId || requestWorkspaceId(req) || '').trim();
+        const role = body?.role === 'reference' ? 'reference' : body?.role === 'image' ? 'image' : 'attachment';
+        if (!assetId || !taskId || !workspaceId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'assetId, taskId, and workspaceId are required.' }));
+            return;
+        }
+        const asset = workspaceAssetStore.get(assetId, workspaceId);
+        if (!asset || asset.deletedAt) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Asset not found.' }));
+            return;
+        }
+        workspaceAssetStore.upsertLink({
+            workspaceId,
+            assetId,
+            taskId,
+            role,
+            deletedAt: null
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, assetId, taskId, workspaceId, role }));
+    });
+    // POST /api/taskforce/admin/orphaned-assets/delete - Hard-delete an orphaned asset from storage and metadata
+    addRoute('POST', '/api/taskforce/admin/orphaned-assets/delete', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        if (!workspaceAssetStore) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Workspace asset store unavailable.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const assetId = String(body?.assetId || '').trim();
+        const workspaceId = String(body?.workspaceId || requestWorkspaceId(req) || '').trim();
+        if (!assetId || !workspaceId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'assetId and workspaceId are required.' }));
+            return;
+        }
+        const asset = workspaceAssetStore.get(assetId, workspaceId);
+        if (!asset || asset.deletedAt) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Asset not found.' }));
+            return;
+        }
+        const objectStorageClient = getObjectStorageClient();
+        const { basePath } = core.getPaths();
+        try {
+            if (asset.storageProvider === 'r2' && objectStorageClient) {
+                await objectStorageClient.deleteObject(asset.storageKey);
+            }
+            else {
+                const fullPath = ensureWithinDir(path.join(basePath, asset.storageKey), basePath);
+                if (fullPath && fs.existsSync(fullPath))
+                    fs.unlinkSync(fullPath);
+            }
+        }
+        catch (error) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || error || 'Failed to delete asset.') }));
+            return;
+        }
+        const deletedAt = new Date().toISOString();
+        workspaceAssetStore.markDeleted(assetId, workspaceId, deletedAt);
+        if (asset.kind === 'image') {
+            core.deleteAnnotatedAttachmentSessionsForImage({
+                workspaceId,
+                imageAssetId: assetId,
+                deletedAt,
+            });
+        }
+        const links = workspaceAssetStore.listLinksForAsset(assetId, workspaceId, { includeDeleted: true });
+        for (const link of links) {
+            workspaceAssetStore.deleteLink({
+                workspaceId,
+                assetId,
+                taskId: link.taskId,
+                role: link.role
+            });
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, assetId, workspaceId }));
+    });
+    // GET /api/taskforce/admin/quarantine - List quarantined assets
+    addRoute('GET', '/api/taskforce/admin/quarantine', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        if (!taskAssetStore && !workspaceAssetStore) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Quarantine is unavailable without DB-backed asset metadata.' }));
+            return;
+        }
+        const reqUrl = new URL(req.url || '/api/taskforce/admin/quarantine', 'http://localhost');
+        const limitRaw = Number(reqUrl.searchParams.get('limit') || '200');
+        const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.min(1000, Math.floor(limitRaw))) : 200;
+        const items = workspaceAssetStore
+            ? workspaceAssetStore.listQuarantined(limit).map((asset) => ({
+                workspaceId: asset.workspaceId,
+                path: asset.storageKey,
+                provider: asset.storageProvider,
+                contentType: asset.mimeType,
+                quarantineStatus: 'quarantined',
+                scan: {
+                    engine: asset.scanEngine || 'none',
+                    verdict: asset.scanStatus === 'infected' ? 'infected' : asset.scanStatus,
+                    details: asset.scanDetails || null,
+                    scannedAt: asset.updatedAt
+                }
+            }))
+            : taskAssetStore.listQuarantined(limit);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, items }));
+    });
+    // POST /api/taskforce/admin/quarantine/delete - Hard-delete quarantined asset from storage + metadata
+    addRoute('POST', '/api/taskforce/admin/quarantine/delete', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const normalizedPath = normalizeDocumentPathInput(body?.path);
+        if (!normalizedPath) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'path is required.' }));
+            return;
+        }
+        const metadata = getAssetMetadata(normalizedPath);
+        if (!metadata) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Metadata not found.' }));
+            return;
+        }
+        if (metadata.quarantineStatus !== 'quarantined') {
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Asset is not quarantined.' }));
+            return;
+        }
+        const objectStorageClient = getObjectStorageClient();
+        const { basePath } = core.getPaths();
+        if (objectStorageClient && metadata.provider === 'r2') {
+            await objectStorageClient.deleteObject(normalizedPath);
+        }
+        else {
+            const filePath = ensureWithinDir(path.join(basePath, normalizedPath), basePath);
+            if (filePath && fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+            }
+        }
+        removeAssetMetadata(normalizedPath);
+        appendStorageTelemetry('quarantine.deleted', {
+            path: normalizedPath,
+            status: 'deleted',
+            provider: metadata.provider
+        });
+        auditAdminAction(req, 'quarantine-delete', { path: normalizedPath, provider: metadata.provider });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, path: normalizedPath }));
+    });
+    // GET /api/taskforce/admin/storage-integrity-settings - Read integrity schedule settings
+    addRoute('GET', '/api/taskforce/admin/storage-integrity-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const settings = resolveStorageIntegrityScheduleSettings(core.getGlobalSettings());
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, settings }));
+    });
+    // POST /api/taskforce/admin/storage-integrity/scan - Scan registry vs local/R2 object integrity
+    addRoute('POST', '/api/taskforce/admin/storage-integrity/scan', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const verifyHash = body?.verifyHash === true;
+        const includeDeleted = body?.includeDeleted === true;
+        const requireMirror = body?.requireMirror === true;
+        const limitRaw = Number(body?.limit);
+        const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.floor(limitRaw)) : 500;
+        const { basePath } = core.getPaths();
+        const result = await scanDocumentIntegrity({
+            basePath,
+            objectStorage: resolveEffectiveObjectStorageConfig(),
+            verifyHash,
+            includeDeleted,
+            requireMirror,
+            limit,
+            assetStore: taskAssetStore || undefined,
+            workspaceAssetStore: workspaceAssetStore || undefined
+        });
+        appendStorageIntegrityHistory(req, {
+            options: { verifyHash, includeDeleted, requireMirror, limit },
+            summary: {
+                totalChecked: result.summary.totalChecked,
+                totalIssues: result.summary.totalIssues,
+                byCode: result.summary.byCode,
+                skippedDeleted: result.summary.skippedDeleted
+            }
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, ...result }));
+    });
+    // POST /api/taskforce/admin/storage-integrity-settings - Save integrity schedule settings
+    addRoute('POST', '/api/taskforce/admin/storage-integrity-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const normalized = normalizeStorageIntegrityScheduleSettings(body || {});
+        core.updateGlobalSettings({ storageIntegritySchedule: normalized });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    });
+    // GET /api/taskforce/admin/storage-integrity/history - List recent integrity scan history
+    addRoute('GET', '/api/taskforce/admin/storage-integrity/history', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const history = getStorageIntegrityHistory();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, history }));
+    });
+    // GET /api/taskforce/admin/document-purge/history - List recent purge runs
+    addRoute('GET', '/api/taskforce/admin/document-purge/history', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const history = getDocumentPurgeHistory();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, history }));
+    });
+    // POST /api/taskforce/admin/storage-integrity/repair - Repair registry state for integrity findings
+    addRoute('POST', '/api/taskforce/admin/storage-integrity/repair', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const action = String(body?.action || '').trim();
+        const normalizedPath = normalizeDocumentPathInput(body?.path);
+        if (!normalizedPath) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'path is required.' }));
+            return;
+        }
+        if (action === 'mark-deleted') {
+            const metadata = markAssetDeleted(normalizedPath);
+            if (!metadata && workspaceAssetStore) {
+                const workspaceId = String(body?.workspaceId || requestWorkspaceId(req) || '').trim() || 'default';
+                const canonicalAsset = workspaceAssetStore.getByStorageKey(normalizedPath, workspaceId);
+                if (canonicalAsset) {
+                    const deletedAt = new Date().toISOString();
+                    const updated = workspaceAssetStore.markDeleted(canonicalAsset.assetId, workspaceId, deletedAt);
+                    if (canonicalAsset.kind === 'image') {
+                        core.deleteAnnotatedAttachmentSessionsForImage({
+                            workspaceId,
+                            imageAssetId: canonicalAsset.assetId,
+                            deletedAt,
+                        });
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ success: true, action, metadata: updated }));
+                    return;
+                }
+            }
+            if (!metadata) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Metadata not found.' }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, action, metadata }));
+            return;
+        }
+        if (action === 'clear-deleted') {
+            const metadata = clearAssetDeleted(normalizedPath);
+            if (!metadata) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Metadata not found.' }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, action, metadata }));
+            return;
+        }
+        if (action === 'remove-entry') {
+            const removed = removeAssetMetadata(normalizedPath);
+            if (!removed) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Metadata not found.' }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, action, path: normalizedPath }));
+            return;
+        }
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Unsupported action. Use mark-deleted, clear-deleted, or remove-entry.' }));
+    });
+    // POST /api/taskforce/admin/workspace-repair/scan - Scan canonical workspace sync surfaces for drift
+    addRoute('POST', '/api/taskforce/admin/workspace-repair/scan', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const workspaceId = String(body?.workspaceId || '').trim() || requestWorkspaceId(req) || 'default';
+        const report = scanWorkspaceRepair({
+            workspaceId,
+            basePath: core.getPaths().basePath,
+            tasks: core.listTasks(workspaceId)?.tasks || [],
+            archivedTasks: core.listArchive(workspaceId)?.archived || [],
+            deletedTasks: core.listWorkspaceSyncDeletes(workspaceId) || [],
+            workspaceAssetStore,
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, ...report }));
+    });
+    // POST /api/taskforce/admin/workspace-repair/apply - Apply deterministic canonical workspace repairs
+    addRoute('POST', '/api/taskforce/admin/workspace-repair/apply', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const workspaceId = String(body?.workspaceId || '').trim() || requestWorkspaceId(req) || 'default';
+        const report = applyWorkspaceRepair({
+            workspaceId,
+            basePath: core.getPaths().basePath,
+            tasks: core.listTasks(workspaceId)?.tasks || [],
+            archivedTasks: core.listArchive(workspaceId)?.archived || [],
+            deletedTasks: core.listWorkspaceSyncDeletes(workspaceId) || [],
+            workspaceAssetStore,
+            upsertDocumentWatermark: (targetWorkspaceId, documentPath, contentHash, updatedAt) => {
+                core.upsertDocumentWatermark(targetWorkspaceId, documentPath, contentHash, updatedAt);
+            }
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, ...report }));
+    });
+    // POST /api/taskforce/admin/object-storage-settings - Save object storage admin overrides
+    addRoute('POST', '/api/taskforce/admin/object-storage-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const keyPrefixRaw = String(body?.keyPrefix ?? '').trim();
+        const uploadTtlRaw = Number(body?.signedUploadTtlSeconds);
+        const downloadTtlRaw = Number(body?.signedDownloadTtlSeconds);
+        const defaults = {
+            keyPrefix: 'taskforce',
+            signedUploadTtlSeconds: 600,
+            signedDownloadTtlSeconds: 300,
+            virusScanAsyncEnabled: true,
+            virusScanFailClosed: baseVirusScanConfig.failClosed
+        };
+        const keyPrefix = typeof body?.keyPrefix === 'string'
+            ? keyPrefixRaw.replace(/^\/+|\/+$/g, '')
+            : defaults.keyPrefix;
+        const signedUploadTtlSeconds = Number.isFinite(uploadTtlRaw) && uploadTtlRaw > 0 ? Math.floor(uploadTtlRaw) : defaults.signedUploadTtlSeconds;
+        const signedDownloadTtlSeconds = Number.isFinite(downloadTtlRaw) && downloadTtlRaw > 0 ? Math.floor(downloadTtlRaw) : defaults.signedDownloadTtlSeconds;
+        const virusScanAsyncEnabled = typeof body?.virusScanAsyncEnabled === 'boolean' ? body.virusScanAsyncEnabled : defaults.virusScanAsyncEnabled;
+        const virusScanFailClosed = typeof body?.virusScanFailClosed === 'boolean' ? body.virusScanFailClosed : defaults.virusScanFailClosed;
+        core.updateGlobalSettings({
+            objectStorage: { keyPrefix, signedUploadTtlSeconds, signedDownloadTtlSeconds, virusScanAsyncEnabled, virusScanFailClosed }
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    });
+    // POST /api/taskforce/admin/system-settings - Save auth/system behavior settings
+    addRoute('POST', '/api/taskforce/admin/system-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const signupMonetizationStrategy = body?.signupMonetizationStrategy === 'plan_selection_required'
+            ? 'plan_selection_required'
+            : 'auto_assign_default';
+        const defaultSignupPlanVersionId = typeof body?.defaultSignupPlanVersionId === 'string'
+            ? body.defaultSignupPlanVersionId.trim() || null
+            : body?.defaultSignupPlanVersionId === null
+                ? null
+                : undefined;
+        const validation = core.validateSignupMonetizationSettings({
+            strategy: signupMonetizationStrategy,
+            ...(defaultSignupPlanVersionId !== undefined ? { defaultSignupPlanVersionId } : {})
+        });
+        if (!validation.valid) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: validation.message || 'Invalid signup monetization settings.', code: validation.code, details: validation.details }));
+            return;
+        }
+        core.updateGlobalSettings({
+            auth: {
+                ...(typeof body?.allowSelfRegistration === 'boolean' ? { allowSelfRegistration: body.allowSelfRegistration } : {}),
+                ...(typeof body?.requireVerifiedEmail === 'boolean' ? { requireVerifiedEmail: body.requireVerifiedEmail } : {}),
+                ...(typeof body?.defaultNewUserBetaAccess === 'boolean' ? { defaultNewUserBetaAccess: body.defaultNewUserBetaAccess } : {}),
+                ...(typeof body?.authRateLimitEnabled === 'boolean' ? { authRateLimitEnabled: body.authRateLimitEnabled } : {}),
+                ...(typeof body?.authRateLimitMaxRequests === 'number' && Number.isFinite(body.authRateLimitMaxRequests)
+                    ? { authRateLimitMaxRequests: Math.max(1, Math.floor(body.authRateLimitMaxRequests)) } : {}),
+                ...(typeof body?.authRateLimitWindowMs === 'number' && Number.isFinite(body.authRateLimitWindowMs)
+                    ? { authRateLimitWindowMs: Math.max(1000, Math.floor(body.authRateLimitWindowMs)) } : {}),
+                signupMonetizationStrategy,
+                ...(defaultSignupPlanVersionId !== undefined ? { defaultSignupPlanVersionId } : {})
+            }
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    });
+    const handlePostSiteSettings = async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        core.updateGlobalSettings({
+            site: {
+                ...(typeof body?.showRunTaskforceLocally === 'boolean'
+                    ? { showRunTaskforceLocally: body.showRunTaskforceLocally }
+                    : {}),
+                ...(typeof body?.pricingPageEnabled === 'boolean'
+                    ? { pricingPageEnabled: body.pricingPageEnabled }
+                    : {})
+            }
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    };
+    addRoute('POST', '/api/taskforce/admin/site-settings', handlePostSiteSettings);
+    addRoute('POST', '/api/taskforce/admin/site_settings', handlePostSiteSettings);
+    // POST /api/taskforce/admin/email-settings - Save email settings (including provider API key)
+    addRoute('POST', '/api/taskforce/admin/email-settings', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        if (!requireCloudRuntime(res, 'Email settings'))
+            return;
+        const body = await parseJsonBody(req);
+        const provider = String(body?.provider || '').trim().toLowerCase();
+        const from = String(body?.from || '').trim();
+        const replyTo = String(body?.replyTo || '').trim();
+        const providerApiKeyRaw = typeof body?.providerApiKey === 'string' ? body.providerApiKey : undefined;
+        const providerApiKey = providerApiKeyRaw?.trim();
+        const clearProviderApiKey = body?.clearProviderApiKey === true;
+        const emailUpdate = {
+            ...(provider === 'console' || provider === 'resend' || provider === 'google-workspace' ? { provider: provider } : {}),
+            ...(from ? { from } : {}),
+            replyTo
+        };
+        if (typeof providerApiKeyRaw === 'string') {
+            emailUpdate.providerApiKey = providerApiKey || '';
+        }
+        else if (clearProviderApiKey) {
+            emailUpdate.providerApiKey = '';
+        }
+        core.updateGlobalSettings({ email: emailUpdate });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+    });
+    // POST /api/taskforce/admin/email-settings/test - Send test email with effective config
+    addRoute('POST', '/api/taskforce/admin/email-settings/test', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: admin role required.' }));
+            return;
+        }
+        if (!requireCloudRuntime(res, 'Test email delivery'))
+            return;
+        const body = await parseJsonBody(req);
+        const to = String(body?.to || '').trim();
+        if (!to || !to.includes('@')) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Valid test email address is required.' }));
+            return;
+        }
+        const config = getEmailConfig();
+        const result = await sendEmail({
+            to,
+            subject: 'Taskforce email settings test',
+            text: `This is a Taskforce test email.\n\nProvider: ${config.provider}\nFrom: ${config.from}\nReply-To: ${config.replyTo || '(none)'}`
+        }, config);
+        if (!result.ok) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: result.error || 'Test email failed.', provider: result.provider }));
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, provider: result.provider, messageId: result.messageId || null }));
+    });
+    // === SECTION: Cloud MCP HTTP transport ===
+    addRoute('POST', '/mcp', async (req, res) => { await handleCloudMcpRequest(req, res); });
+    addRoute('POST', '/mcp/', async (req, res) => { await handleCloudMcpRequest(req, res); });
+    addRoute('GET', '/mcp', async (req, res) => { await handleCloudMcpRequest(req, res); });
+    addRoute('GET', '/mcp/', async (req, res) => { await handleCloudMcpRequest(req, res); });
+    addRoute('DELETE', '/mcp', async (req, res) => { await handleCloudMcpRequest(req, res); });
+    addRoute('DELETE', '/mcp/', async (req, res) => { await handleCloudMcpRequest(req, res); });
+    addRoute('OPTIONS', '/mcp', async (_req, res) => {
+        res.writeHead(204, {
+            'Access-Control-Allow-Origin': '*',
+            'Access-Control-Allow-Headers': 'authorization, content-type, accept, last-event-id, mcp-protocol-version, mcp-session-id, x-taskforce-workspace-id, x-taskforce-ai-profile-token, x-taskforce-ai-name, x-taskforce-ai-description, x-taskforce-ai-role, x-taskforce-ai-provider, x-taskforce-ai-model, x-taskforce-ai-surface-type',
+            'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS'
+        });
+        res.end();
+    });
+    addRoute('OPTIONS', '/mcp/', async (_req, res) => {
+        res.writeHead(204, {
+            'Access-Control-Allow-Origin': '*',
+            'Access-Control-Allow-Headers': 'authorization, content-type, accept, last-event-id, mcp-protocol-version, mcp-session-id, x-taskforce-workspace-id, x-taskforce-ai-profile-token, x-taskforce-ai-name, x-taskforce-ai-description, x-taskforce-ai-role, x-taskforce-ai-provider, x-taskforce-ai-model, x-taskforce-ai-surface-type',
+            'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS'
+        });
+        res.end();
+    });
+    // === SECTION: MCP OAuth 2.0 ===
+    addRoute('GET', '/.well-known/oauth-authorization-server', async (req, res) => {
+        const issuer = resolveMcpOauthIssuer(req);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            issuer,
+            authorization_endpoint: resolveMcpOauthAuthorizeUrl(req),
+            token_endpoint: resolveMcpOauthTokenUrl(req),
+            registration_endpoint: resolveMcpOauthRegisterUrl(req),
+            response_types_supported: ['code'],
+            grant_types_supported: ['authorization_code'],
+            token_endpoint_auth_methods_supported: ['none'],
+            code_challenge_methods_supported: ['S256'],
+            scopes_supported: ['tasks:read', 'tasks:write', 'workspace:read'],
+        }));
+    });
+    addRoute('GET', '/.well-known/oauth-protected-resource', async (req, res) => {
+        const issuer = resolveMcpOauthIssuer(req);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            resource: resolveMcpOauthResourceUrl(req),
+            authorization_servers: [issuer],
+            bearer_methods_supported: ['header'],
+        }));
+    });
+    addRoute('POST', '/oauth/mcp/register', async (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const body = await parseJsonBody(req);
+        try {
+            const provider = (() => {
+                const explicit = String(body?.provider || '').trim().toLowerCase();
+                if (explicit === 'chatgpt' || explicit === 'claude')
+                    return explicit;
+                const values = Array.isArray(body?.redirect_uris) ? body.redirect_uris : [];
+                for (const value of values) {
+                    try {
+                        const hostname = new URL(String(value || '').trim()).hostname.toLowerCase();
+                        if (hostname.includes('anthropic.com') || hostname.includes('claude.ai'))
+                            return 'claude';
+                        if (hostname.includes('openai.com') || hostname.includes('chatgpt.com') || hostname.includes('chat.openai.com'))
+                            return 'chatgpt';
+                    }
+                    catch { /* ignore invalid redirect URI */ }
+                }
+                return 'chatgpt';
+            })();
+            const client = core.registerMcpOAuthClient({
+                provider,
+                clientName: body?.client_name,
+                redirectUris: body?.redirect_uris,
+            });
+            res.writeHead(201, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                client_id: client.id,
+                client_name: client.clientName,
+                redirect_uris: client.redirectUris,
+                grant_types: ['authorization_code'],
+                response_types: ['code'],
+                token_endpoint_auth_method: 'none',
+                scope: 'tasks:read tasks:write workspace:read',
+            }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: 'invalid_client_metadata',
+                error_description: error.message,
+                code: error?.code || 'MCP_OAUTH_CLIENT_CREATE_FAILED',
+            }));
+        }
+    });
+    addRoute('GET', '/oauth/mcp/authorize', async (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const reqUrl = new URL(req.url || '/oauth/mcp/authorize', resolveMcpOauthIssuer(req));
+        const clientId = String(reqUrl.searchParams.get('client_id') || '').trim();
+        const redirectUri = String(reqUrl.searchParams.get('redirect_uri') || '').trim();
+        const responseType = String(reqUrl.searchParams.get('response_type') || '').trim();
+        const state = String(reqUrl.searchParams.get('state') || '').trim();
+        const codeChallenge = String(reqUrl.searchParams.get('code_challenge') || '').trim();
+        const codeChallengeMethod = String(reqUrl.searchParams.get('code_challenge_method') || 'S256').trim() || 'S256';
+        const scopes = normalizeMcpOauthScopeString(reqUrl.searchParams.get('scope'));
+        if (responseType !== 'code' || !clientId || !redirectUri || !codeChallenge) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'invalid_request', error_description: 'client_id, redirect_uri, response_type=code, and code_challenge are required.' }));
+            return;
+        }
+        const access = context.authConfig ? resolveRequestAccess(req, context.authConfig) : null;
+        if (!access?.authenticated || !access.userId || access.userId === 'anonymous') {
+            res.writeHead(302, { Location: `${resolveCloudLoginBaseUrl(req)}/login?next=${encodeURIComponent(reqUrl.toString())}` });
+            res.end();
+            return;
+        }
+        try {
+            const clientRecord = core.getMcpOAuthClient(clientId);
+            if (!clientRecord)
+                throw new TaskforceRuleError('OAuth client not found', 404, 'MCP_OAUTH_CLIENT_NOT_FOUND');
+            if (!clientRecord.redirectUris.includes(redirectUri))
+                throw new TaskforceRuleError('Redirect URI is not registered for this OAuth client', 400, 'MCP_OAUTH_REDIRECT_URI_INVALID');
+            const workspaces = core.listUserWorkspaces(access.userId)
+                .map((workspace) => ({ id: String(workspace.id || '').trim(), name: String(workspace.name || workspace.slug || workspace.id || 'Workspace'), role: String(workspace.role || 'member') }))
+                .filter((workspace) => Boolean(workspace.id));
+            if (workspaces.length === 0)
+                throw new TaskforceRuleError('No accessible workspaces found for this user', 403, 'MCP_OAUTH_WORKSPACE_REQUIRED');
+            const preferredWorkspaceId = workspaces.find((workspace) => workspace.id === String(access.workspaceId || '').trim())?.id || workspaces[0].id;
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(renderMcpOauthAuthorizePage({ userName: String(access.userId), workspaces, preselectedWorkspaceId: preferredWorkspaceId, clientName: clientRecord.clientName, clientId: clientRecord.id, redirectUri, scopes, state, codeChallenge, codeChallengeMethod }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'invalid_request', error_description: error.message, code: error?.code || 'MCP_OAUTH_AUTHORIZE_FAILED' }));
+        }
+    });
+    addRoute('POST', '/oauth/mcp/authorize', async (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const access = context.authConfig ? resolveRequestAccess(req, context.authConfig) : null;
+        if (!access?.authenticated || !access.userId || access.userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'login_required' }));
+            return;
+        }
+        const body = await parseFormBody(req);
+        const clientId = String(body.client_id || '').trim();
+        const redirectUri = String(body.redirect_uri || '').trim();
+        const state = String(body.state || '').trim();
+        const workspaceId = String(body.workspaceId || '').trim();
+        const decision = String(body.decision || 'deny').trim().toLowerCase();
+        if (!clientId || !redirectUri) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'invalid_request', error_description: 'client_id and redirect_uri are required.' }));
+            return;
+        }
+        if (decision !== 'approve') {
+            const denyTarget = new URL(redirectUri);
+            denyTarget.searchParams.set('error', 'access_denied');
+            if (state)
+                denyTarget.searchParams.set('state', state);
+            res.writeHead(302, { Location: denyTarget.toString() });
+            res.end();
+            return;
+        }
+        try {
+            const scopes = normalizeMcpOauthScopeString(body.scope);
+            const clientRecord = core.getMcpOAuthClient(clientId);
+            if (!clientRecord)
+                throw new TaskforceRuleError('OAuth client not found', 404, 'MCP_OAUTH_CLIENT_NOT_FOUND');
+            const issued = core.issueMcpOAuthAuthorizationCode({
+                provider: clientRecord.provider,
+                clientId,
+                userId: access.userId,
+                workspaceId,
+                scopes,
+                redirectUri,
+                codeChallenge: String(body.code_challenge || '').trim(),
+                codeChallengeMethod: String(body.code_challenge_method || 'S256').trim() || 'S256',
+            });
+            core.addAdminAuditLog({
+                action: 'mcp.connector.authorize',
+                actorUserId: access.userId,
+                actorRole: String(access.role || 'member'),
+                workspaceId,
+                details: { provider: clientRecord.provider, clientId, scopes }
+            });
+            const approveTarget = new URL(redirectUri);
+            approveTarget.searchParams.set('code', issued.code);
+            if (state)
+                approveTarget.searchParams.set('state', state);
+            res.writeHead(302, { Location: approveTarget.toString() });
+            res.end();
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'access_denied', error_description: error.message, code: error?.code || 'MCP_OAUTH_AUTHORIZE_FAILED' }));
+        }
+    });
+    addRoute('POST', '/oauth/mcp/token', async (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const body = await parseFormBody(req);
+        if (String(body.grant_type || '').trim() !== 'authorization_code') {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'unsupported_grant_type', error_description: 'Only authorization_code is supported.' }));
+            return;
+        }
+        try {
+            const clientId = String(body.client_id || '').trim();
+            const clientRecord = core.getMcpOAuthClient(clientId);
+            if (!clientRecord)
+                throw new TaskforceRuleError('OAuth client not found', 404, 'MCP_OAUTH_CLIENT_NOT_FOUND');
+            const result = core.exchangeMcpOAuthAuthorizationCode({
+                provider: clientRecord.provider,
+                clientId,
+                code: String(body.code || '').trim(),
+                redirectUri: String(body.redirect_uri || '').trim(),
+                codeVerifier: String(body.code_verifier || '').trim(),
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+            res.end(JSON.stringify({ access_token: result.accessToken, token_type: result.tokenType, scope: result.scopes.join(' ') }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'invalid_grant', error_description: error.message, code: error?.code || 'MCP_OAUTH_TOKEN_EXCHANGE_FAILED' }));
+        }
+    });
+    // === SECTION: MCP token and connector settings ===
+    addRoute('GET', '/api/taskforce/settings/mcp/tokens', async (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const userId = resolveAuthenticatedUserId(req);
+        if (!userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const reqUrl = new URL(req.url || '/api/taskforce/settings/mcp/tokens', 'http://localhost');
+        const page = Number.parseInt(String(reqUrl.searchParams.get('page') || '1'), 10);
+        const pageSize = Number.parseInt(String(reqUrl.searchParams.get('pageSize') || '20'), 10);
+        try {
+            const result = core.listMcpAccessTokens({ userId, workspaceId: requestWorkspaceId(req), page, pageSize });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, ...result }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message, code: error?.code || 'MCP_TOKEN_LIST_FAILED' }));
+        }
+    });
+    addRoute('GET', '/api/taskforce/settings/mcp/connectors', async (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const userId = resolveAuthenticatedUserId(req);
+        if (!userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const reqUrl = new URL(req.url || '/api/taskforce/settings/mcp/connectors', 'http://localhost');
+        const provider = String(reqUrl.searchParams.get('provider') || '').trim();
+        try {
+            const items = core.listMcpOAuthConnectorGrants({ userId, workspaceId: requestWorkspaceId(req), provider: provider || null });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, items }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message, code: error?.code || 'MCP_CONNECTOR_LIST_FAILED' }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/settings/mcp/connectors/:id/disconnect', async (req, res, params) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const userId = resolveAuthenticatedUserId(req);
+        if (!userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const wid = requestWorkspaceId(req);
+        try {
+            const record = core.revokeMcpOAuthConnectorGrant({ actorUserId: userId, workspaceId: wid, grantId: params.id });
+            core.addAdminAuditLog({ action: 'mcp.connector.disconnect', actorUserId: userId, actorRole: requestRole(req), workspaceId: wid, details: { provider: record.provider, clientId: record.clientId, grantId: record.id } });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, record }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message, code: error?.code || 'MCP_CONNECTOR_DISCONNECT_FAILED' }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/settings/mcp/tokens', async (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const userId = resolveAuthenticatedUserId(req);
+        if (!userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        try {
+            const created = core.createMcpAccessToken({ userId, workspaceId: requestWorkspaceId(req), name: body?.name, scopes: body?.scopes, expiresAt: typeof body?.expiresAt === 'string' ? body.expiresAt : null, createdByIp: req.socket?.remoteAddress || null });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, token: created.token, record: created.record }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message, code: error?.code || 'MCP_TOKEN_CREATE_FAILED' }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/settings/mcp/tokens/:id/revoke', async (req, res, params) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const userId = resolveAuthenticatedUserId(req);
+        if (!userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        try {
+            const record = core.revokeMcpAccessToken({ actorUserId: userId, workspaceId: requestWorkspaceId(req), tokenId: params.id });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, record }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message, code: error?.code || 'MCP_TOKEN_REVOKE_FAILED' }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/settings/mcp/tokens/:id/regenerate', async (req, res, params) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const userId = resolveAuthenticatedUserId(req);
+        if (!userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        try {
+            const regenerated = core.regenerateMcpAccessToken({ actorUserId: userId, workspaceId: requestWorkspaceId(req), tokenId: params.id, createdByIp: req.socket?.remoteAddress || null });
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, token: regenerated.token, record: regenerated.record }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message, code: error?.code || 'MCP_TOKEN_REGENERATE_FAILED' }));
+        }
+    });
+    addRoute('POST', '/api/taskforce/settings/mcp/test-connection', async (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return;
+        const userId = resolveAuthenticatedUserId(req);
+        if (!userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const token = typeof body?.token === 'string' ? body.token.trim() : '';
+        if (!token) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Token is required.', code: 'MCP_TOKEN_REQUIRED' }));
+            return;
+        }
+        const wid = requestWorkspaceId(req);
+        const requiredScopes = Array.isArray(body?.requiredScopes)
+            ? body.requiredScopes.map((scope) => String(scope || '').trim()).filter((scope) => MCP_TOKEN_SCOPE_VALUES.has(scope))
+            : [];
+        try {
+            core.listMcpAccessTokens({ userId, workspaceId: wid, page: 1, pageSize: 1 });
+            const inspection = core.inspectMcpAccessToken(token);
+            if (!inspection) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Token is invalid.', code: 'MCP_TOKEN_INVALID' }));
+                return;
+            }
+            if (inspection.status === 'revoked') {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Token has been revoked.', code: 'MCP_TOKEN_REVOKED' }));
+                return;
+            }
+            if (inspection.status === 'expired') {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Token has expired.', code: 'MCP_TOKEN_EXPIRED' }));
+                return;
+            }
+            if (inspection.workspaceId !== wid) {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Token belongs to a different workspace.', code: 'MCP_TOKEN_WORKSPACE_MISMATCH', details: { expectedWorkspaceId: wid, tokenWorkspaceId: inspection.workspaceId } }));
+                return;
+            }
+            const missingScopes = requiredScopes.filter((scope) => !inspection.scopes.includes(scope));
+            if (missingScopes.length > 0) {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Token is missing required scopes.', code: 'MCP_TOKEN_MISSING_SCOPES', details: { requiredScopes, missingScopes, grantedScopes: inspection.scopes } }));
+                return;
+            }
+            const workspace = core.getWorkspaceProfile(wid);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, result: { tokenId: inspection.tokenId, tokenName: inspection.name, workspaceId: wid, workspaceName: String(workspace?.name || wid), scopes: inspection.scopes, requiredScopes, endpoint: '/mcp' } }));
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: error.message, code: error?.code || 'MCP_TEST_CONNECTION_FAILED' }));
+        }
+    });
+}