@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/server/routes/admin.js

@@ -55,39 +55,34 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { TaskforceRuleError } from '../../core/Taskforce.js';
-import { escapeHtml, parseFormBody, parseJsonBody } from './primitives.js';
+import { classifyMcpOAuthClientProduct } from '../../mcp/clientRegistry.js';
+import { escapeHtml, formatApiErrorResponse, parseFormBody, parseJsonBody } from './primitives.js';
 import { resolveRequestAccess } from '../auth.js';
 import { 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 { parseAiProfileBootstrapHeaders } from '../../mcp/aiProfileBootstrap.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { createTaskHttpDurableRouters } from './durableTaskHttpRouters.js';
+import { getDocumentReferenceLabel } from '../../utils/documentReferences.js';
+import { getImageReferenceLabel } from '../../utils/imageReferences.js';
 import { randomUUID } from 'crypto';
 import { resolveDeploymentConfig } from '../../config/deployment.js';
 import { getTaskforceCloudEnvironmentConfig, resolveTaskforceCloudEnvironmentFromBaseUrl, resolveTaskforceMcpBaseUrlFromBaseUrl } from '../../config/cloudEnvironment.js';
-import { buildCloudMcpRuntimeAuth, resolveErrorStatusCode } from './shared.js';
+import { makeHandleCloudMcpRequest, resolveErrorStatusCode } from './shared.js';
 import { buildAuthBehavior, buildSiteBehavior, getRouteEmailConfig, resolvePublicAuthBaseUrl, resolveRuntimeConfigBaseUrl, } from './authSupport.js';
 import { applyWorkspaceRepair, scanWorkspaceRepair } from '../../sync/workspaceRepair.js';
 import { testMintAppleClientSecret } from '../auth/providers/appleClientSecret.js';
+import { isAiProfileAvatarStorageKey } from '../../utils/aiProfileAvatarPaths.js';
 const PRICING_PAGE_DESCRIPTION_MAX_LENGTH = 2000;
 const OPENAI_APPS_CHALLENGE_TOKEN = 'o9iBeJDuKPMtnKm5-B8OROga3bWDkJS6PBIg6JT9Izs';
 // === 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, 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 { addRoute, core, context, requestWorkspaceId, requestUserId, requestRole, ensureAppAccess, ensureAdminRole, ensureCloudPlanData, requireCloudRuntime, resolveAuthenticatedUserId, resolveAdminRequestActor, auditAdminAction, resolveEffectiveObjectStorageConfig, getObjectStorageClient, taskAssetStore, publishedContentResolver, normalizeDocumentPathInput, ensureWithinDir, getAssetMetadata, markAssetDeleted, clearAssetDeleted, removeAssetMetadata, getStorageTelemetry, appendStorageTelemetry, getStorageIntegrityHistory, appendStorageIntegrityHistory, getDocumentPurgeHistory, appendDocumentPurgeHistory, getCollaborationTelemetry, isCollaborationPolicyEnabled, normalizeMcpOauthScopeString, MCP_TOKEN_SCOPE_VALUES, 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;
-    const isAiProfileAvatarStorageKey = (storageKey, workspaceId) => {
-        const normalized = String(storageKey || '').replace(/\\/g, '/');
-        return normalized.startsWith(`workspaces/${workspaceId}/assets/images/ai-profiles/`)
-            && normalized.includes('/avatar/');
-    };
     const listReferencedAiProfileAvatarStorageKeys = (workspaceId) => {
         const referenced = new Set();
         const profiles = typeof core.listAiProfiles === 'function'
@@ -119,18 +114,6 @@ export function registerAdminRoutes(deps) {
     };
     // === SECTION: MCP helpers ===
     const MCP_CONNECTION_TEST_TIMEOUT_MS = 5000;
-    const writeMcpHttpError = (res, statusCode, message, data) => {
-        res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({
-            jsonrpc: '2.0',
-            error: {
-                code: -32000,
-                message,
-                ...(data ? { data } : {}),
-            },
-            id: null,
-        }));
-    };
     const resolveMcpOauthIssuer = (req) => {
         const runtimeBaseUrl = resolveRuntimeConfigBaseUrl(req);
         if (runtimeBaseUrl)
@@ -348,295 +331,16 @@ export function registerAdminRoutes(deps) {
 </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 bootstrap = parseAiProfileBootstrapHeaders(req.headers);
-        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,
-                ...bootstrap,
-                aiProfileToken: bootstrap.aiProfileToken || oauthAuth?.aiProfileToken || null,
-                aiProfileName: bootstrap.aiProfileName || oauthAuth?.aiProfileName || null,
-            };
-        }
-        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 requestId = String(req.headers['x-request-id'] || req.headers['x-railway-request-id'] || '').trim() || randomUUID();
-        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,
-                    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;
-        let runtime = null;
-        try {
-            runtime = createTaskforceMcpServer({
-                projectRoot: core.getPaths().projectRoot,
-                tenantId: core.getTenantId(),
-                workspaceId: auth.workspaceId,
-                core,
-                serverName: 'taskforce-cloud',
-                logStartup: false,
-                runtimeMode: 'cloud',
-                auth: buildCloudMcpRuntimeAuth({
-                    req,
-                    auth,
-                    requestHeader,
-                    requestId,
-                    authScopes,
-                }),
-            });
-            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) {
-            console.error('[Taskforce MCP] Cloud transport request failed:', {
-                requestId,
-                kind: 'tool_transport_failure',
-                message: error instanceof Error ? error.message : String(error),
-            });
-            if (!res.headersSent) {
-                writeMcpHttpError(res, 500, 'MCP transport failure.', {
-                    kind: 'tool_transport_failure',
-                    retryable: true,
-                    requestId,
-                });
-            }
-        }
-        finally {
-            if (runtime) {
-                try {
-                    await runtime.server.close();
-                }
-                catch (closeError) {
-                    console.warn('[Taskforce MCP] Cloud transport cleanup failed:', closeError);
-                }
-            }
-        }
-    };
+    const handleCloudMcpRequest = makeHandleCloudMcpRequest(core, {
+        ensureAppAccess,
+        resolveAuthenticatedUserId,
+        writeRateLimit: {
+            enabled: MCP_WRITE_RATE_LIMIT_ENABLED,
+            actorMaxRequests: MCP_WRITE_RATE_LIMIT_ACTOR_MAX_REQUESTS,
+            workspaceMaxRequests: MCP_WRITE_RATE_LIMIT_WORKSPACE_MAX_REQUESTS,
+            windowMs: MCP_WRITE_RATE_LIMIT_WINDOW_MS,
+        },
+    });
     // === SECTION: Platform plan management ===
     addRoute('GET', '/api/platform/plans', async (req, res) => {
         if (!ensureCloudPlanData(req, res))
@@ -1198,6 +902,16 @@ export function registerAdminRoutes(deps) {
         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/audit-logs/diagnostics - Retention and storage health
+    addRoute('GET', '/api/taskforce/admin/audit-logs/diagnostics', async (req, res) => {
+        if (!ensureAdminRole(req)) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Forbidden: system admin role required.' }));
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(core.getAdminAuditRetentionDiagnostics()));
+    });
     // 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)) {
@@ -1728,7 +1442,8 @@ export function registerAdminRoutes(deps) {
         const assets = workspaceAssetStore.listAllByWorkspace(workspaceId, {
             includeDeleted: false
         }).filter((asset) => (!aiProfileAvatarStorageKeys.has(asset.storageKey)
-            && workspaceAssetStore.listLinksForAsset(asset.assetId, workspaceId).every((link) => !!link.deletedAt)))
+            && workspaceAssetStore.listLinksForAsset(asset.assetId, workspaceId).every((link) => !!link.deletedAt)
+            && core.getWorkspaceAssetDispatchReadiness(asset.assetId, workspaceId).ready))
             .map((asset) => ({
             assetId: asset.assetId,
             workspaceId: asset.workspaceId,
@@ -1738,7 +1453,15 @@ export function registerAdminRoutes(deps) {
             storageProvider: asset.storageProvider,
             updatedAt: asset.updatedAt,
             sizeBytes: asset.sizeBytes,
-            documentId: asset.documentId
+            documentId: asset.documentId,
+            referenceNumber: asset.referenceNumber,
+            referenceLabel: asset.kind === 'document'
+                ? getDocumentReferenceLabel(asset)
+                : asset.kind === 'image' ? getImageReferenceLabel(asset) : null,
+            candidateType: asset.kind === 'document'
+                && asset.originalFilename.trim().toLowerCase() === 'implementation-plan.md'
+                ? 'task-plan'
+                : 'asset'
         }));
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ success: true, assets }));
@@ -1765,21 +1488,118 @@ export function registerAdminRoutes(deps) {
             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.' }));
+        const db = core.getDatabaseAdapter();
+        const postCommitNotifications = [];
+        let recovery;
+        try {
+            recovery = db.transaction(() => {
+                // Lock both recovery identities before checking invariants. The no-op updates
+                // take row locks in Postgres and a write lock in SQLite, so concurrent
+                // recoveries cannot attach one asset twice or install competing task plans.
+                db.prepare(`
+                    UPDATE tasks SET updated_at = updated_at
+                    WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+                `).run(core.getTenantId(), workspaceId, taskId);
+                db.prepare(`
+                    UPDATE workspace_assets SET updated_at = updated_at
+                    WHERE tenant_id = ? AND workspace_id = ? AND asset_id = ?
+                `).run(core.getTenantId(), workspaceId, assetId);
+                const asset = workspaceAssetStore.get(assetId, workspaceId);
+                if (!asset || asset.deletedAt) {
+                    throw new TaskforceRuleError('Asset not found.', 404, 'WORKSPACE_ASSET_NOT_FOUND');
+                }
+                const task = core.getTask(taskId, workspaceId);
+                if (!task) {
+                    throw new TaskforceRuleError('Task not found.', 404, 'TASK_NOT_FOUND');
+                }
+                const readiness = core.getWorkspaceAssetDispatchReadiness(assetId, workspaceId);
+                if (!readiness.ready) {
+                    throw new TaskforceRuleError(readiness.reason || 'Workspace asset content is not ready.', readiness.retryable ? 425 : 400, readiness.retryable ? 'WORKSPACE_ASSET_NOT_READY' : 'WORKSPACE_ASSET_INVALID');
+                }
+                const effectiveRole = asset.storageProvider === 'external'
+                    ? 'reference'
+                    : role;
+                const activeLinks = workspaceAssetStore.listLinksForAsset(assetId, workspaceId);
+                const exactRetry = activeLinks.length === 1
+                    && activeLinks[0].targetType === 'task'
+                    && activeLinks[0].targetId === taskId
+                    && activeLinks[0].role === effectiveRole;
+                if (activeLinks.length > 0 && !exactRetry) {
+                    throw new TaskforceRuleError('Asset is not orphaned.', 409, 'WORKSPACE_ASSET_NOT_ORPHANED');
+                }
+                const isCanonicalPlan = asset.kind === 'document'
+                    && asset.originalFilename.trim().toLowerCase() === 'implementation-plan.md';
+                if (isCanonicalPlan) {
+                    const competingPlan = workspaceAssetStore.listLinksForTask(taskId, workspaceId)
+                        .map((link) => workspaceAssetStore.get(link.assetId, workspaceId))
+                        .find((linkedAsset) => (linkedAsset
+                        && !linkedAsset.deletedAt
+                        && linkedAsset.assetId !== assetId
+                        && linkedAsset.kind === 'document'
+                        && linkedAsset.originalFilename.trim().toLowerCase() === 'implementation-plan.md'));
+                    if (competingPlan) {
+                        throw new TaskforceRuleError('Task already has a canonical implementation plan.', 409, 'TASK_CANONICAL_PLAN_CONFLICT', {
+                            existingAssetId: competingPlan.assetId,
+                            existingReferenceLabel: getDocumentReferenceLabel(competingPlan)
+                        });
+                    }
+                }
+                const durableRouters = createTaskHttpDurableRouters({ core, context, req, workspaceId });
+                const attachmentLinksRouter = durableRouters.createAttachmentLinksRouter(undefined, (notify) => postCommitNotifications.push(notify));
+                if (attachmentLinksRouter.enabled) {
+                    const links = core.listTaskAttachmentLinksForDurableSync(taskId, workspaceId)
+                        .filter((link) => link.assetId !== assetId)
+                        .map((link, order) => ({ ...link, order }));
+                    links.push({
+                        assetId,
+                        role: effectiveRole,
+                        order: links.length,
+                        referenceNumber: asset.referenceNumber || null,
+                        referenceLabel: asset.referenceNumber
+                            ? (asset.kind === 'document'
+                                ? getDocumentReferenceLabel(asset)
+                                : asset.kind === 'image' ? getImageReferenceLabel(asset) : null)
+                            : null,
+                    });
+                    attachmentLinksRouter.replace({ taskId, links });
+                }
+                else if (!exactRetry) {
+                    workspaceAssetStore.upsertLink({
+                        workspaceId,
+                        assetId,
+                        taskId,
+                        role: effectiveRole,
+                        deletedAt: null
+                    });
+                }
+                return { asset, effectiveRole };
+            })();
+        }
+        catch (error) {
+            const formatted = formatApiErrorResponse(error);
+            res.writeHead(formatted.statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(formatted.body));
             return;
         }
-        workspaceAssetStore.upsertLink({
-            workspaceId,
+        for (const notify of postCommitNotifications) {
+            try {
+                notify();
+            }
+            catch (error) {
+                console.warn('[Taskforce] Orphaned asset recovery notification failed.', error);
+            }
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
             assetId,
             taskId,
-            role,
-            deletedAt: null
-        });
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ success: true, assetId, taskId, workspaceId, role }));
+            workspaceId,
+            role: recovery.effectiveRole,
+            referenceLabel: recovery.asset.kind === 'document'
+                ? getDocumentReferenceLabel(recovery.asset)
+                : recovery.asset.kind === 'image' ? getImageReferenceLabel(recovery.asset) : null
+        }));
     });
     // 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) => {
@@ -1812,6 +1632,8 @@ export function registerAdminRoutes(deps) {
             res.end(JSON.stringify({ error: 'Asset is still referenced by an AI profile avatar.' }));
             return;
         }
+        const deletedAt = new Date().toISOString();
+        workspaceAssetStore.markDeleted(assetId, workspaceId, deletedAt);
         const objectStorageClient = getObjectStorageClient();
         const { basePath } = core.getPaths();
         try {
@@ -1825,12 +1647,11 @@ export function registerAdminRoutes(deps) {
             }
         }
         catch (error) {
+            workspaceAssetStore.restoreDeleted(assetId, workspaceId, asset.updatedAt);
             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,
@@ -1955,7 +1776,7 @@ export function registerAdminRoutes(deps) {
         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({
+        const scanOptions = {
             basePath,
             objectStorage: resolveEffectiveObjectStorageConfig(),
             verifyHash,
@@ -1963,8 +1784,13 @@ export function registerAdminRoutes(deps) {
             requireMirror,
             limit,
             assetStore: taskAssetStore || undefined,
-            workspaceAssetStore: workspaceAssetStore || undefined
-        });
+        };
+        const result = await scanDocumentIntegrity(workspaceAssetStore ? {
+            ...scanOptions,
+            workspaceAssetStore,
+            tenantId: core.getTenantId(),
+            publishedContentResolver,
+        } : scanOptions);
         appendStorageIntegrityHistory(req, {
             options: { verifyHash, includeDeleted, requireMirror, limit },
             summary: {
@@ -2028,10 +1854,12 @@ export function registerAdminRoutes(deps) {
             return;
         }
         if (action === 'mark-deleted') {
+            const workspaceId = String(body?.workspaceId || requestWorkspaceId(req) || '').trim() || 'default';
+            const canonicalAsset = workspaceAssetStore?.getByStorageKey(normalizedPath, workspaceId) || null;
+            if (canonicalAsset)
+                workspaceAssetStore.assertAssetDeletionAllowed(canonicalAsset.assetId, workspaceId);
             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);
@@ -2091,12 +1919,17 @@ export function registerAdminRoutes(deps) {
         const body = await parseJsonBody(req);
         const workspaceId = String(body?.workspaceId || '').trim() || requestWorkspaceId(req) || 'default';
         const report = scanWorkspaceRepair({
+            tenantId: core.getTenantId(),
             workspaceId,
             basePath: core.getPaths().basePath,
             tasks: core.listTasks(workspaceId)?.tasks || [],
             archivedTasks: core.listArchive(workspaceId)?.archived || [],
             deletedTasks: core.listWorkspaceSyncDeletes(workspaceId) || [],
             workspaceAssetStore,
+            publishedContentResolver,
+            aiProfiles: typeof core.listAiProfiles === 'function'
+                ? core.listAiProfiles(workspaceId, { includeArchived: true }) || []
+                : [],
         });
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ success: true, ...report }));
@@ -2111,12 +1944,18 @@ export function registerAdminRoutes(deps) {
         const body = await parseJsonBody(req);
         const workspaceId = String(body?.workspaceId || '').trim() || requestWorkspaceId(req) || 'default';
         const report = applyWorkspaceRepair({
+            tenantId: core.getTenantId(),
             workspaceId,
             basePath: core.getPaths().basePath,
             tasks: core.listTasks(workspaceId)?.tasks || [],
             archivedTasks: core.listArchive(workspaceId)?.archived || [],
             deletedTasks: core.listWorkspaceSyncDeletes(workspaceId) || [],
             workspaceAssetStore,
+            publishedContentResolver,
+            repairMissingAssetLinks: true,
+            aiProfiles: typeof core.listAiProfiles === 'function'
+                ? core.listAiProfiles(workspaceId, { includeArchived: true }) || []
+                : [],
             upsertDocumentWatermark: (targetWorkspaceId, documentPath, contentHash, updatedAt) => {
                 core.upsertDocumentWatermark(targetWorkspaceId, documentPath, contentHash, updatedAt);
             }
@@ -2541,7 +2380,7 @@ export function registerAdminRoutes(deps) {
     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-icon, x-taskforce-ai-color, x-taskforce-ai-description, x-taskforce-ai-role, x-taskforce-ai-provider, x-taskforce-ai-model, x-taskforce-ai-surface-type',
+            'Access-Control-Allow-Headers': 'authorization, content-type, accept, last-event-id, mcp-protocol-version, mcp-session-id, x-taskforce-workspace-id, x-taskforce-mcp-client-id, x-taskforce-ai-profile-token, x-taskforce-ai-name, x-taskforce-ai-icon, x-taskforce-ai-color, 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, HEAD, POST, DELETE, OPTIONS'
         });
         res.end();
@@ -2549,7 +2388,7 @@ export function registerAdminRoutes(deps) {
     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-icon, x-taskforce-ai-color, x-taskforce-ai-description, x-taskforce-ai-role, x-taskforce-ai-provider, x-taskforce-ai-model, x-taskforce-ai-surface-type',
+            'Access-Control-Allow-Headers': 'authorization, content-type, accept, last-event-id, mcp-protocol-version, mcp-session-id, x-taskforce-workspace-id, x-taskforce-mcp-client-id, x-taskforce-ai-profile-token, x-taskforce-ai-name, x-taskforce-ai-icon, x-taskforce-ai-color, 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, HEAD, POST, DELETE, OPTIONS'
         });
         res.end();
@@ -2619,13 +2458,15 @@ export function registerAdminRoutes(deps) {
         }));
     });
     addRoute('POST', '/oauth/mcp/register', async (req, res) => {
+        if (!requireCloudRuntime(res, 'MCP OAuth'))
+            return;
         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')
+                if (explicit === 'chatgpt' || explicit === 'claude' || explicit === 'grok' || explicit === 'gemini' || explicit === 'mistral' || explicit === 'perplexity')
                     return explicit;
                 const values = Array.isArray(body?.redirect_uris) ? body.redirect_uris : [];
                 for (const value of values) {
@@ -2633,6 +2474,14 @@ export function registerAdminRoutes(deps) {
                         const hostname = new URL(String(value || '').trim()).hostname.toLowerCase();
                         if (hostname.includes('anthropic.com') || hostname.includes('claude.ai'))
                             return 'claude';
+                        if (hostname === 'grok.com' || hostname.endsWith('.grok.com') || hostname === 'x.ai' || hostname.endsWith('.x.ai'))
+                            return 'grok';
+                        if (hostname === 'gemini.google.com' || hostname.endsWith('.gemini.google.com'))
+                            return 'gemini';
+                        if (hostname === 'mistral.ai' || hostname.endsWith('.mistral.ai'))
+                            return 'mistral';
+                        if (hostname === 'perplexity.ai' || hostname.endsWith('.perplexity.ai'))
+                            return 'perplexity';
                         if (hostname.includes('openai.com') || hostname.includes('chatgpt.com') || hostname.includes('chat.openai.com'))
                             return 'chatgpt';
                     }
@@ -2644,6 +2493,11 @@ export function registerAdminRoutes(deps) {
                 provider,
                 clientName: body?.client_name,
                 redirectUris: body?.redirect_uris,
+                productClientId: classifyMcpOAuthClientProduct({
+                    provider,
+                    clientName: body?.client_name,
+                    redirectUris: body?.redirect_uris,
+                }),
             });
             res.writeHead(201, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
@@ -2667,6 +2521,8 @@ export function registerAdminRoutes(deps) {
         }
     });
     addRoute('GET', '/oauth/mcp/authorize', async (req, res) => {
+        if (!requireCloudRuntime(res, 'MCP OAuth'))
+            return;
         if (!ensureAppAccess(req, res))
             return;
         const reqUrl = new URL(req.url || '/oauth/mcp/authorize', resolveMcpOauthIssuer(req));
@@ -2723,6 +2579,8 @@ export function registerAdminRoutes(deps) {
         }
     });
     addRoute('HEAD', '/oauth/mcp/authorize', async (req, res) => {
+        if (!requireCloudRuntime(res, 'MCP OAuth'))
+            return;
         if (!ensureAppAccess(req, res))
             return;
         const reqUrl = new URL(req.url || '/oauth/mcp/authorize', resolveMcpOauthIssuer(req));
@@ -2779,6 +2637,8 @@ export function registerAdminRoutes(deps) {
         }
     });
     addRoute('POST', '/oauth/mcp/authorize', async (req, res) => {
+        if (!requireCloudRuntime(res, 'MCP OAuth'))
+            return;
         if (!ensureAppAccess(req, res))
             return;
         const access = context.authConfig ? resolveRequestAccess(req, context.authConfig) : null;
@@ -2843,6 +2703,8 @@ export function registerAdminRoutes(deps) {
         }
     });
     addRoute('POST', '/oauth/mcp/token', async (req, res) => {
+        if (!requireCloudRuntime(res, 'MCP OAuth'))
+            return;
         if (!ensureAppAccess(req, res))
             return;
         const body = await parseFormBody(req);