@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/server/index.js

@@ -7,14 +7,19 @@
 import * as http from 'http';
 import * as fs from 'fs';
 import * as path from 'path';
+import { createHash } from 'crypto';
 import { fileURLToPath } from 'url';
 import { WebSocketServer } from 'ws';
 import chokidar from 'chokidar';
 import { TaskforceCore } from '../core/Taskforce.js';
 import { createRoutes, matchRoute } from './routes.js';
+import { formatApiErrorResponse } from './routes/primitives.js';
+import { logSlowBootstrapRoute } from './routes/shared.js';
 import { applyCorsHeaders, getAllowedOriginsFromEnv } from './cors.js';
 import { applyPrefixedRateLimitHeaders, applyRateLimitHeaders, InMemoryRateLimiter, resolveRateLimitKey } from './rateLimit.js';
 import { isRequestAuthorized, resolveAuthConfigFromEnv, resolveRequestAccess } from './auth.js';
+import { resolveAuthorizedWorkspaceAccess, resolveDisabledAccessError, } from './authorizedWorkspaceAccess.js';
+export { resolveAuthorizedWorkspaceAccess, resolveDisabledAccessError, isWorkspaceAccessRecoveryRoute, } from './authorizedWorkspaceAccess.js';
 import { assertCloudDatabaseProvider, resolveRuntimeModeFromEnv } from './runtimeMode.js';
 import { applySecurityHeaders } from './securityHeaders.js';
 import { resolveDatabaseConfigFromEnv } from '../storage/providerConfig.js';
@@ -23,11 +28,20 @@ import { purgeExpiredDocuments } from '../storage/documentPurge.js';
 import { scanDocumentIntegrity } from '../storage/documentIntegrity.js';
 import { resolveStorageIntegrityScheduleSettings, shouldRunStorageIntegritySchedule } from '../storage/integritySchedule.js';
 import { TaskAssetStore } from '../storage/taskAssetStore.js';
-import { WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
 import { validateEnvironment } from '../config/envSchema.js';
 import { createRealtimeSyncWsManager } from './realtimeSyncWs.js';
 import { resolveDeploymentConfig } from '../config/deployment.js';
 import { TASKFORCE_CLOUD_ENVIRONMENTS, parseTaskforceCloudEnvironment } from '../config/cloudEnvironment.js';
+import { resolveWorkflowRuntimeMutationCapability } from '../sync/v3/durableWorkflowRuntimeMutationRouter.js';
+import { createWorkspaceSyncCloudCredentialValidator } from '../sync/coordinator/workspaceSyncCloudCredentialValidator.js';
+import { bootstrapVerifiedWorkspaceSyncAccess } from '../sync/coordinator/workspaceSyncLocalAccessBootstrap.js';
+import { rewriteSetCookieForLocalHost } from '../utils/httpSetCookie.js';
+import { createWorkspaceSyncServerComposition, shutdownWorkspaceSyncServerComposition, } from './localWorkspaceSyncServerComposition.js';
+import { LocalServiceSessionManager } from './localServiceSessions.js';
+import { LocalSyncIdentityStore } from '../sync/v3/localSyncIdentityStore.js';
+import { shouldBroadcastLocalFileInvalidation } from './localRealtimeFileInvalidation.js';
+import { resolveCloudCollectionReadOperation, } from './cloudCollectionRead.js';
+import { CloudCollectionReadPool, resolveCloudCollectionReadPoolSize, shouldUseCloudCollectionReadPool, } from './cloudCollectionReadPool.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const MIME_TYPES = {
@@ -41,8 +55,41 @@ const MIME_TYPES = {
     '.woff2': 'font/woff2',
     '.ttf': 'font/ttf',
 };
+export function isLocalSyncCoordinatorOwnedPath(pathname) {
+    if (!pathname.startsWith('/api/taskforce/sync/'))
+        return false;
+    return pathname !== '/api/taskforce/sync/v3/local/operations'
+        && pathname !== '/api/taskforce/sync/v3/local/metadata-ownership'
+        && pathname !== '/api/taskforce/sync/events'
+        && pathname !== '/api/taskforce/sync/v3/diagnostics'
+        && pathname !== '/api/taskforce/sync/user-settings'
+        && pathname !== '/api/taskforce/sync/workspace/provision';
+}
+export async function closeTaskforceTransports(server, wss, graceMs = 15_000) {
+    wss.clients.forEach((client) => client.close());
+    await new Promise((resolve) => {
+        if (!server.listening) {
+            resolve();
+            return;
+        }
+        const forceCloseTimer = setTimeout(() => {
+            wss.clients.forEach((client) => client.terminate());
+            server.closeAllConnections?.();
+        }, graceMs);
+        forceCloseTimer.unref?.();
+        server.close(() => {
+            clearTimeout(forceCloseTimer);
+            resolve();
+        });
+    });
+    await new Promise((resolve) => {
+        wss.close(() => resolve());
+    });
+}
 function resolveStaticUiPath() {
+    const configuredUiPath = String(process.env.TASKFORCE_UI_DIST_DIR || '').trim();
     const candidates = [
+        ...(configuredUiPath ? [path.resolve(configuredUiPath)] : []),
         // Current output layout
         path.resolve(__dirname, '../../dist/ui'),
         // Legacy/alternative layouts from older package builds
@@ -102,9 +149,6 @@ const REFRESH_DIAGNOSTIC_PATH_PREFIXES = [
     '/api/taskforce/priorities',
     '/api/taskforce/taxonomies',
     '/api/taskforce/initiative-templates',
-    '/api/taskforce/workflow-templates',
-    '/api/taskforce/workflow-editor/overrides',
-    '/api/taskforce/environments',
     '/api/taskforce/sync/'
 ];
 const REFRESH_DIAGNOSTIC_DURATION_MS = 100;
@@ -134,21 +178,6 @@ export const TASKFORCE_PROXY_ORIGIN_PROTO_HEADER = 'x-taskforce-origin-proto';
 export const TASKFORCE_PROXY_ORIGIN_BASE_URL_HEADER = 'x-taskforce-origin-base-url';
 export const TASKFORCE_PROXY_ORIGIN_RUNTIME_HEADER = 'x-taskforce-origin-runtime';
 export const TASKFORCE_PROXY_CLOUD_ENVIRONMENT_HEADER = 'x-taskforce-cloud-environment';
-export function isWorkspaceAccessRecoveryRoute(pathname) {
-    return pathname === '/api/taskforce/workspaces'
-        || pathname === '/api/taskforce/session/workspace';
-}
-export function resolveDisabledAccessError(access, pathname) {
-    if (pathname.startsWith('/api/taskforce/auth/'))
-        return null;
-    if (access.accountDisabled ?? access.disabled) {
-        return 'Forbidden: user account is disabled.';
-    }
-    if (access.workspaceDisabled && !isWorkspaceAccessRecoveryRoute(pathname)) {
-        return 'Forbidden: workspace access is not active for this user.';
-    }
-    return null;
-}
 function shouldLogRefreshDiagnostic(pathname) {
     return REFRESH_DIAGNOSTIC_PATH_PREFIXES.some((prefix) => pathname === prefix || pathname.startsWith(prefix));
 }
@@ -167,21 +196,53 @@ function isCloudOwnedUserAvatarContextPath(pathname) {
         return false;
     }
 }
+function isWorkspaceAiProfileAvatarContextPath(pathname) {
+    const prefix = '/api/taskforce/context/';
+    if (!pathname.startsWith(prefix))
+        return false;
+    try {
+        const decodedPath = decodeURIComponent(pathname.slice(prefix.length)).replace(/\\/g, '/');
+        return /^workspaces\/[^/]+\/assets\/ai-profiles\/[^/]+\/avatar\/[^/]+$/i.test(decodedPath);
+    }
+    catch {
+        return false;
+    }
+}
+function isTaskforceAgentAvatarGenerationPath(pathname) {
+    return /^\/api\/taskforce\/agents\/[^/]+\/avatar\/generate$/i.test(pathname)
+        || pathname === '/api/taskforce/workspace/ai-profiles/avatar/generate';
+}
 export function shouldProxyCloudPath(pathname) {
     if (!pathname)
         return false;
     if (pathname === '/api/taskforce/auth/runtime-config')
         return false;
+    if (pathname === '/api/taskforce/sync/v3/diagnostics')
+        return false;
     if (pathname === '/api/taskforce/sync/workspace/apply-local')
         return false;
+    if (pathname === '/api/taskforce/sync/workspace/content-manifest')
+        return false;
+    if (pathname === '/api/taskforce/sync/workspace/content-obligations')
+        return false;
+    if (pathname === '/api/taskforce/sync/workspace/content-obligations/failures')
+        return false;
     if (pathname === '/api/taskforce/sync/workspace/documents')
         return false;
     if (pathname === '/api/taskforce/sync/workspace/assets')
         return false;
     if (pathname === '/api/taskforce/sync/workspace/ai-profiles')
         return false;
+    if (pathname === '/api/taskforce/sync/workspace/document-reviews')
+        return false;
+    if (pathname === '/api/taskforce/sync/workspace/annotated-attachments')
+        return false;
+    if (pathname === '/api/taskforce/sync/workspace/taskforce-agents')
+        return false;
     if (pathname === '/api/taskforce/sync/events')
         return false;
+    if (pathname.startsWith('/api/taskforce/sync/v3/local/'))
+        return false;
     return pathname === PUBLIC_PRICING_PATH
         || pathname === PUBLIC_SITE_CONFIG_PATH
         || pathname === PUBLIC_SITE_CONFIG_SCRIPT_PATH
@@ -189,45 +250,47 @@ export function shouldProxyCloudPath(pathname) {
         || pathname === '/api/taskforce/account/entitlements'
         || pathname === '/api/taskforce/account/profile-summary'
         || pathname === '/api/taskforce/account/team-management-access'
+        || pathname === '/api/taskforce/workspaces'
+        || pathname.startsWith('/api/taskforce/workspaces/')
         || pathname.startsWith('/api/taskforce/admin/')
         || pathname.startsWith('/api/taskforce/billing/')
         || pathname.startsWith('/api/taskforce/auth/')
+        || pathname === '/api/taskforce/agents/model-gateway/test'
         || isCloudOwnedUserAvatarContextPath(pathname)
+        || isTaskforceAgentAvatarGenerationPath(pathname)
         || pathname.startsWith('/api/taskforce/settings/mcp/')
         || pathname.startsWith('/api/platform/')
         || pathname.startsWith('/api/taskforce/sync/');
 }
+export function shouldProxyCloudRequest(url, env = process.env) {
+    if (shouldProxyCloudPath(url.pathname))
+        return true;
+    if (url.searchParams.get('taskforceCloud') !== '1')
+        return false;
+    if (url.pathname === '/api/taskforce/sync/v3/diagnostics')
+        return true;
+    if (url.pathname === '/api/taskforce/ui-state')
+        return true;
+    if (url.pathname === '/api/taskforce/session/workspace')
+        return true;
+    if (isWorkspaceAiProfileAvatarContextPath(url.pathname))
+        return true;
+    if (/^\/api\/taskforce\/workflow-executions\/[^/]+\/complete-step$/.test(url.pathname)) {
+        return !resolveWorkflowRuntimeMutationCapability({
+            runtimeMode: 'local',
+            surface: 'http',
+            env,
+        });
+    }
+    return url.pathname === '/api/taskforce/workspace/ai-profiles/avatar'
+        || url.pathname === '/api/taskforce/workspace/ai-profiles/avatar/upload';
+}
 export function resolveCloudProxyUpstreamBaseUrl(req, fallbackBaseUrl) {
     const requestedEnvironment = parseTaskforceCloudEnvironment(req.headers[TASKFORCE_PROXY_CLOUD_ENVIRONMENT_HEADER]);
     if (!requestedEnvironment)
         return fallbackBaseUrl;
     return TASKFORCE_CLOUD_ENVIRONMENTS[requestedEnvironment].appBaseUrl;
 }
-export function resolveAuthorizedWorkspaceAccess(core, access, requestedWorkspaceId) {
-    if (!access.authenticated || !access.userId || access.userId === 'anonymous')
-        return access;
-    const trimmedRequestedWorkspaceId = String(requestedWorkspaceId || '').trim();
-    const candidateWorkspaceIds = [
-        trimmedRequestedWorkspaceId,
-        String(access.workspaceId || '').trim()
-    ].filter((workspaceId, index, values) => Boolean(workspaceId) && values.indexOf(workspaceId) === index);
-    for (const workspaceId of candidateWorkspaceIds) {
-        const resolved = core.resolveUserAccess(access.userId, workspaceId, access.role);
-        if (!resolved)
-            continue;
-        return {
-            ...access,
-            role: resolved.role,
-            workspaceId: resolved.workspaceId,
-            userId: resolved.userId,
-            systemRole: core.getSystemRole(resolved.userId),
-            disabled: resolved.disabled,
-            accountDisabled: resolved.accountDisabled ?? resolved.disabled,
-            workspaceDisabled: resolved.workspaceDisabled ?? false
-        };
-    }
-    return access;
-}
 export function shouldApplyReadOnlyMutationGuard(methodRaw, pathname) {
     const method = String(methodRaw || 'GET').toUpperCase();
     if (method !== 'POST' && method !== 'PATCH' && method !== 'DELETE')
@@ -283,6 +346,11 @@ export function applyCloudProxyForwardedHeaders(headers, req) {
     const proto = String(req.headers['x-forwarded-proto'] || '').trim().toLowerCase() === 'https'
         ? 'https'
         : (req.socket?.encrypted ? 'https' : 'http');
+    // The fetch implementation decodes gzip/deflate/Brotli responses, but can
+    // leave newer encodings such as zstd untouched. Since response framing
+    // headers are removed below, request an identity body so the browser never
+    // receives encoded bytes without the matching Content-Encoding header.
+    headers.set('accept-encoding', 'identity');
     if (originalHost && !headers.has('x-forwarded-host')) {
         headers.set('x-forwarded-host', originalHost);
     }
@@ -297,12 +365,7 @@ export function applyCloudProxyForwardedHeaders(headers, req) {
     }
 }
 export function rewriteProxySetCookieForLocalHost(cookie) {
-    const parts = String(cookie || '').split(';').map((part) => part.trim()).filter(Boolean);
-    if (parts.length === 0)
-        return cookie;
-    const [nameValue, ...attrs] = parts;
-    const filteredAttrs = attrs.filter((attr) => !attr.toLowerCase().startsWith('domain='));
-    return [nameValue, ...filteredAttrs].join('; ');
+    return rewriteSetCookieForLocalHost(cookie);
 }
 function normalizeHostHeaderHost(hostHeader) {
     const raw = String(hostHeader || '').trim().toLowerCase();
@@ -414,8 +477,13 @@ export function createStandaloneServer(options) {
     const db = resolveDatabaseConfigFromEnv();
     const runtimeMode = resolveRuntimeModeFromEnv(process.env, db.provider);
     assertCloudDatabaseProvider(runtimeMode, db.provider, process.env);
+    if (runtimeMode === 'local' && !options.localSyncProcessLock) {
+        throw new Error('Local Taskforce server startup requires the sync coordinator process lock. '
+            + 'Use acquireLocalSyncProcessLockForRuntime before createStandaloneServer.');
+    }
     const core = new TaskforceCore({
         projectRoot: options.projectRoot,
+        localDataOwnerPermit: options.localDataOwnerPermit,
         tenantId: process.env.TASKFORCE_TENANT_ID || 'default',
         runtimeMode,
         database: {
@@ -425,11 +493,14 @@ export function createStandaloneServer(options) {
     });
     const { basePath } = core.getPaths();
     const taskAssetStore = new TaskAssetStore(core.getDatabaseAdapter(), core.getTenantId());
-    const workspaceAssetStore = new WorkspaceAssetStore(core.getDatabaseAdapter(), core.getTenantId());
     const authConfig = resolveAuthConfigFromEnv(runtimeMode, process.env);
     authConfig.excludedPaths = ensureBillingWebhookAuthExclusion(authConfig.excludedPaths);
     authConfig.excludedPaths = ensurePublicPricingAuthExclusion(authConfig.excludedPaths);
     authConfig.excludedPaths = ensurePublicSiteConfigAuthExclusion(authConfig.excludedPaths);
+    const cloudProxyBaseUrl = resolveCloudProxyBaseUrl(process.env);
+    const cloudProxyEnabled = runtimeMode === 'local' && Boolean(cloudProxyBaseUrl);
+    const cloudProxyClientId = String(process.env.TASKFORCE_CF_ACCESS_CLIENT_ID || process.env.CF_ACCESS_CLIENT_ID || '').trim();
+    const cloudProxyClientSecret = String(process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET || process.env.CF_ACCESS_CLIENT_SECRET || '').trim();
     const objectStorage = resolveObjectStorageConfigFromEnv(process.env);
     const resolveEffectiveObjectStorage = () => {
         if (objectStorage.provider !== 'r2' || !objectStorage.r2)
@@ -458,15 +529,130 @@ export function createStandaloneServer(options) {
             }
         };
     };
+    const cloudflareAccess = cloudProxyClientId && cloudProxyClientSecret
+        ? { clientId: cloudProxyClientId, clientSecret: cloudProxyClientSecret }
+        : null;
+    const workspaceSyncComposition = createWorkspaceSyncServerComposition({
+        core,
+        runtimeMode,
+        processLock: options.localSyncProcessLock,
+        localBasePath: basePath,
+        resolveObjectStorageConfig: resolveEffectiveObjectStorage,
+        cloudBaseUrl: cloudProxyBaseUrl,
+        sessionCookieName: authConfig.sessionCookieName,
+        validateWorkspaceAccess: (workspaceId, principal) => {
+            if (principal.tenantId !== core.getTenantId()) {
+                throw new Error('Sync coordinator principal does not belong to this tenant.');
+            }
+            const access = core.resolveUserAccess(principal.userId, workspaceId);
+            if (!access || access.disabled || access.workspaceDisabled) {
+                throw new Error('Sync coordinator principal does not have active workspace access.');
+            }
+        },
+        validateCredential: createWorkspaceSyncCloudCredentialValidator({
+            cloudBaseUrl: cloudProxyBaseUrl,
+            tenantId: core.getTenantId(),
+            cloudflareAccess,
+            onValidated: (validation) => {
+                bootstrapVerifiedWorkspaceSyncAccess(core, validation);
+            },
+        }),
+        cloudflareAccess,
+        env: process.env,
+        reportInternalError: (error, source) => {
+            console.error(`[taskforce] Local workspace sync runtime error source=${source}:`, String(error?.message || error));
+        },
+    });
+    const localWorkspaceSyncRuntime = workspaceSyncComposition.runtime;
+    const localSyncCoordinatorServices = workspaceSyncComposition.routeServices;
+    const localSyncCoordinatorHost = localWorkspaceSyncRuntime?.host || null;
+    const workspaceAssetStore = workspaceSyncComposition.serverDataServices.workspaceAssetStore;
+    if (!workspaceAssetStore) {
+        throw new Error('Workspace asset storage requires a database-backed Taskforce core.');
+    }
+    const publishedContentResolver = workspaceSyncComposition.serverDataServices.publishedContentResolver;
+    let localSyncPermitRecoveryTimer = null;
+    if (localSyncCoordinatorServices && localSyncCoordinatorHost) {
+        const { permitStore, transportGateway, } = localSyncCoordinatorServices;
+        localSyncPermitRecoveryTimer = setInterval(() => {
+            const workspaceId = localSyncCoordinatorHost.readState().activeWorkspaceId;
+            if (!workspaceId)
+                return;
+            try {
+                permitStore.recoverExpiredPermits({
+                    currentServerInstanceId: localSyncCoordinatorHost.serverInstanceId,
+                    workspaceId,
+                    excludePermitIds: transportGateway.inFlightPermitIds,
+                });
+            }
+            catch {
+                try {
+                    core.recordSyncEvent(workspaceId, {
+                        eventType: 'apply',
+                        status: 'error',
+                        errorMessage: 'Local sync execution permit recovery failed.',
+                        details: {
+                            source: 'coordinator.permit-recovery',
+                            code: 'SYNC_COORDINATOR_PERMIT_RECOVERY_FAILED',
+                        },
+                    });
+                }
+                catch {
+                    console.error('[taskforce] Local sync execution permit recovery failed; diagnostics are unavailable.');
+                }
+            }
+        }, 1_000);
+        localSyncPermitRecoveryTimer.unref?.();
+    }
+    let localServiceServer = null;
+    const localServiceSessions = options.localService
+        ? new LocalServiceSessionManager(options.localService.generation)
+        : null;
     const routes = createRoutes(core, {
         authConfig,
-        objectStorage: resolveEffectiveObjectStorage()
+        objectStorage: resolveEffectiveObjectStorage(),
+        localSyncCoordinator: localSyncCoordinatorServices,
+        workspaceSyncDataServices: workspaceSyncComposition.serverDataServices,
+        localService: options.localService && localServiceSessions ? {
+            ...options.localService,
+            projectIdentity: createHash('sha256')
+                .update(path.resolve(options.projectRoot))
+                .digest('hex'),
+            operationClientId: new LocalSyncIdentityStore(core.getDatabaseAdapter()).getOrCreateClientId(),
+            sessions: localServiceSessions,
+            requestShutdown: () => {
+                if (!localServiceServer)
+                    return;
+                void localServiceServer.shutdownTaskforce().catch((error) => {
+                    console.error('[Taskforce] Local service administrative shutdown failed:', error);
+                });
+            },
+            diagnostics: () => ({
+                coordinator: localSyncCoordinatorHost?.readState() || null,
+            }),
+            endpoint: () => {
+                const address = localServiceServer?.address();
+                return address && typeof address === 'object'
+                    ? `http://127.0.0.1:${address.port}`
+                    : null;
+            },
+        } : undefined,
     });
-    const allowedOrigins = getAllowedOriginsFromEnv(process.env.TASKFORCE_ALLOWED_ORIGINS);
-    const cloudProxyBaseUrl = resolveCloudProxyBaseUrl(process.env);
-    const cloudProxyEnabled = runtimeMode === 'local' && Boolean(cloudProxyBaseUrl);
-    const cloudProxyClientId = String(process.env.TASKFORCE_CF_ACCESS_CLIENT_ID || process.env.CF_ACCESS_CLIENT_ID || '').trim();
-    const cloudProxyClientSecret = String(process.env.TASKFORCE_CF_ACCESS_CLIENT_SECRET || process.env.CF_ACCESS_CLIENT_SECRET || '').trim();
+    const cloudCollectionReadWorkerCount = resolveCloudCollectionReadPoolSize(process.env);
+    const cloudCollectionReadPool = shouldUseCloudCollectionReadPool({
+        runtimeMode,
+        databaseProvider: db.provider,
+        connectionString: db.connectionString,
+        workerCount: cloudCollectionReadWorkerCount,
+    })
+        ? new CloudCollectionReadPool({
+            projectRoot: options.projectRoot,
+            tenantId: core.getTenantId(),
+            connectionString: db.connectionString,
+            size: cloudCollectionReadWorkerCount,
+        })
+        : null;
+    const allowedOrigins = getAllowedOriginsFromEnv(process.env.TASKFORCE_ALLOWED_ORIGINS, runtimeMode);
     const rateLimitEnabled = typeof process.env.TASKFORCE_API_RATE_LIMIT_ENABLED === 'string'
         ? process.env.TASKFORCE_API_RATE_LIMIT_ENABLED !== 'false'
         : (runtimeMode === 'cloud');
@@ -636,6 +822,9 @@ export function createStandaloneServer(options) {
     }
     const integritySchedulePollMinutes = readPositiveInteger(process.env.TASKFORCE_STORAGE_INTEGRITY_SCHEDULE_POLL_MINUTES, 1);
     console.log(`[Taskforce] Storage integrity scheduler poll: every ${integritySchedulePollMinutes} minute(s)`);
+    const adminAuditRetentionEnabled = runtimeMode === 'cloud'
+        && process.env.TASKFORCE_ADMIN_AUDIT_RETENTION_ENABLED !== 'false';
+    const adminAuditRetentionIntervalMinutes = readPositiveInteger(process.env.TASKFORCE_ADMIN_AUDIT_RETENTION_INTERVAL_MINUTES, 15);
     const server = http.createServer(async (req, res) => {
         const requestStartedAt = getRequestTimingNow();
         if (!distUiPath) {
@@ -644,7 +833,17 @@ export function createStandaloneServer(options) {
         }
         const url = new URL(req.url || '/', `http://localhost`);
         const isMcpPath = url.pathname === '/mcp' || url.pathname === '/mcp/' || url.pathname.startsWith('/mcp/');
+        const isSharedLocalServicePath = Boolean(options.localService) && (url.pathname === '/mcp'
+            || url.pathname.startsWith('/api/taskforce/local-service/v1/'));
         applySecurityHeaders(res, runtimeMode, process.env);
+        if (isSharedLocalServicePath && String(req.headers.origin || '').trim()) {
+            res.writeHead(403, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: 'Browser-origin requests are not accepted by the local service.',
+                code: 'BROWSER_ORIGIN_REJECTED',
+            }));
+            return;
+        }
         // Handle CORS preflight
         if (req.method === 'OPTIONS') {
             const cors = applyCorsHeaders(req, res, allowedOrigins);
@@ -658,7 +857,18 @@ export function createStandaloneServer(options) {
             res.end();
             return;
         }
-        if (cloudProxyEnabled && shouldProxyCloudPath(url.pathname)) {
+        if (runtimeMode === 'local'
+            && options.localSyncProcessLock
+            && !options.localSyncProcessLock.owned
+            && isLocalSyncCoordinatorOwnedPath(url.pathname)) {
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                error: 'Another local Taskforce process owns workspace synchronization.',
+                code: 'SYNC_COORDINATOR_OWNED_BY_OTHER_PROCESS',
+            }));
+            return;
+        }
+        if (cloudProxyEnabled && shouldProxyCloudRequest(url)) {
             const cors = applyCorsHeaders(req, res, allowedOrigins);
             if (!cors.allowed) {
                 res.writeHead(403, { 'Content-Type': 'application/json' });
@@ -827,12 +1037,47 @@ export function createStandaloneServer(options) {
                         return;
                     }
                 }
-                const auth = isRequestAuthorized(req, authConfig);
+                const auth = isSharedLocalServicePath
+                    ? { allowed: true }
+                    : isRequestAuthorized(req, authConfig);
                 if (!auth.allowed) {
                     res.writeHead(401, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: auth.reason || 'Unauthorized' }));
                     return;
                 }
+                const cloudCollectionReadOperation = cloudCollectionReadPool
+                    ? resolveCloudCollectionReadOperation(req.method, url.pathname)
+                    : null;
+                if (cloudCollectionReadPool && cloudCollectionReadOperation) {
+                    try {
+                        const requestedWorkspaceId = Array.isArray(req.headers['x-taskforce-workspace-id'])
+                            ? String(req.headers['x-taskforce-workspace-id'][0] || '')
+                            : String(req.headers['x-taskforce-workspace-id'] || '');
+                        const response = await cloudCollectionReadPool.execute({
+                            operation: cloudCollectionReadOperation,
+                            pathname: url.pathname,
+                            requestedWorkspaceId,
+                            access: accessForRateLimit,
+                            performanceTrace: String(req.headers['x-taskforce-performance-trace'] || '').trim() === '1',
+                        });
+                        if (response.performance) {
+                            logSlowBootstrapRoute({
+                                route: url.pathname,
+                                workspaceId: response.workspaceId,
+                                traceId: String(req.headers['x-taskforce-bootstrap-trace-id'] || '').trim(),
+                                durationMs: response.performance.durationMs,
+                                details: response.performance.details,
+                            });
+                        }
+                        response.headers['X-Taskforce-Cloud-Read-Execution'] = 'worker';
+                        res.writeHead(response.statusCode, response.headers);
+                        res.end(response.body);
+                        return;
+                    }
+                    catch (error) {
+                        console.error(`[Taskforce] Cloud collection read worker failed; using synchronous fallback path=${url.pathname}:`, error instanceof Error ? error.message : String(error));
+                    }
+                }
                 const pathname = url.pathname;
                 const isMutation = shouldApplyReadOnlyMutationGuard(req.method, pathname);
                 let access = accessForRateLimit;
@@ -854,7 +1099,7 @@ export function createStandaloneServer(options) {
                     ? String(req.headers['x-taskforce-user-id'][0] || '')
                     : String(req.headers['x-taskforce-user-id'] || '');
                 req.headers['x-taskforce-user-id'] = resolveEffectiveRequestUserId(access.userId, explicitRequestUserId);
-                if (isCollaborationPolicyEnabled() && isMutation && access.role === 'read-only') {
+                if (!isSharedLocalServicePath && isCollaborationPolicyEnabled() && isMutation && access.role === 'read-only') {
                     res.writeHead(403, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'Forbidden: read-only role cannot mutate data.' }));
                     return;
@@ -863,11 +1108,9 @@ export function createStandaloneServer(options) {
             }
             catch (error) {
                 console.error('[Taskforce] API error:', error);
-                const statusCode = Number.isFinite(Number(error?.statusCode))
-                    ? Math.max(400, Math.min(599, Number(error.statusCode)))
-                    : 500;
+                const { statusCode, body } = formatApiErrorResponse(error);
                 res.writeHead(statusCode, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: error.message }));
+                res.end(JSON.stringify(body));
             }
             finally {
                 res.writeHead = originalWriteHead;
@@ -921,6 +1164,65 @@ export function createStandaloneServer(options) {
     const offRealtimeMutation = core.onRealtimeMutation((event) => {
         realtimeWsManager.broadcastMutation(event);
     });
+    localServiceServer = server;
+    let purgeTimer = null;
+    let integrityScheduleTimer = null;
+    let adminAuditRetentionTimer = null;
+    let watcher = null;
+    let shutdownPromise = null;
+    Object.defineProperty(server, 'localSyncCoordinatorHost', {
+        value: localSyncCoordinatorHost,
+        enumerable: true,
+        configurable: false,
+        writable: false,
+    });
+    server.shutdownTaskforce = () => {
+        if (shutdownPromise)
+            return shutdownPromise;
+        shutdownPromise = (async () => {
+            if (purgeTimer) {
+                clearInterval(purgeTimer);
+                purgeTimer = null;
+            }
+            if (integrityScheduleTimer) {
+                clearInterval(integrityScheduleTimer);
+                integrityScheduleTimer = null;
+            }
+            if (adminAuditRetentionTimer) {
+                clearInterval(adminAuditRetentionTimer);
+                adminAuditRetentionTimer = null;
+            }
+            if (localSyncPermitRecoveryTimer) {
+                clearInterval(localSyncPermitRecoveryTimer);
+                localSyncPermitRecoveryTimer = null;
+            }
+            const activeWatcher = watcher;
+            watcher = null;
+            offRealtimeMutation();
+            await shutdownWorkspaceSyncServerComposition({
+                runtime: localWorkspaceSyncRuntime,
+                closeTransports: async () => {
+                    const [watcherResult, serverResult] = await Promise.allSettled([
+                        activeWatcher?.close(),
+                        closeTaskforceTransports(server, wss),
+                    ]);
+                    if (watcherResult.status === 'rejected') {
+                        if (serverResult.status === 'rejected') {
+                            throw new AggregateError([watcherResult.reason, serverResult.reason], 'File watcher and HTTP/WebSocket shutdown both failed.');
+                        }
+                        throw watcherResult.reason;
+                    }
+                    if (serverResult.status === 'rejected') {
+                        throw serverResult.reason;
+                    }
+                    await cloudCollectionReadPool?.close();
+                },
+                closeCore: () => core.close(),
+            });
+            await options.afterShutdown?.();
+        })();
+        return shutdownPromise;
+    };
     // Prevent WebSocketServer from crashing the process on server errors (like EADDRINUSE)
     wss.on('error', (err) => {
         // Only log if it's not a bind error (which we handle in CLI)
@@ -929,8 +1231,20 @@ export function createStandaloneServer(options) {
         }
     });
     server.once('listening', () => {
-        let purgeTimer = null;
-        let integrityScheduleTimer = null;
+        const runAdminAuditRetention = () => {
+            const result = core.pruneAdminAuditLogs();
+            if (result.failed) {
+                console.warn(`[Taskforce] Admin audit retention failed: ${result.error}`);
+            }
+            else if (result.deleted > 0 || result.remainingEligible > 0) {
+                console.log(`[Taskforce] Admin audit retention: deleted=${result.deleted} remainingEligible=${result.remainingEligible}`);
+            }
+        };
+        if (adminAuditRetentionEnabled) {
+            runAdminAuditRetention();
+            adminAuditRetentionTimer = setInterval(runAdminAuditRetention, adminAuditRetentionIntervalMinutes * 60_000);
+            adminAuditRetentionTimer.unref?.();
+        }
         const appendDocumentPurgeHistory = (summary) => {
             const settings = core.getGlobalSettings();
             const existing = Array.isArray(settings?.documentPurgeHistory)
@@ -990,6 +1304,7 @@ export function createStandaloneServer(options) {
                     return;
                 const { basePath } = core.getPaths();
                 const result = await scanDocumentIntegrity({
+                    tenantId: core.getTenantId(),
                     basePath,
                     objectStorage: resolveEffectiveObjectStorage(),
                     verifyHash: schedule.verifyHash,
@@ -997,7 +1312,8 @@ export function createStandaloneServer(options) {
                     requireMirror: schedule.requireMirror,
                     limit: schedule.limit,
                     assetStore: taskAssetStore,
-                    workspaceAssetStore
+                    workspaceAssetStore,
+                    publishedContentResolver
                 });
                 core.updateGlobalSettings({
                     storageIntegritySchedule: {
@@ -1033,37 +1349,30 @@ export function createStandaloneServer(options) {
             realtimeWsManager.handleConnection(ws, req);
         });
         // Use chokidar for cross-platform file watching (works on Linux)
-        const watcher = chokidar.watch(basePath, {
+        watcher = chokidar.watch(basePath, {
             persistent: true,
             ignoreInitial: true,
             awaitWriteFinish: { stabilityThreshold: 100 }
         });
         watcher.on('change', (filepath) => {
-            if (filepath.endsWith('.json') || filepath.endsWith('.db') || filepath.endsWith('.db-wal')) {
+            if (shouldBroadcastLocalFileInvalidation(filepath)) {
                 console.log(`[Taskforce] File changed: ${path.basename(filepath)}`);
                 realtimeWsManager.broadcastTaskforceUpdate();
             }
         });
-        // Graceful shutdown
         const shutdown = () => {
             console.log('\n[Taskforce] Shutting down...');
-            if (purgeTimer) {
-                clearInterval(purgeTimer);
-                purgeTimer = null;
-            }
-            if (integrityScheduleTimer) {
-                clearInterval(integrityScheduleTimer);
-                integrityScheduleTimer = null;
-            }
-            watcher.close();
-            offRealtimeMutation();
-            wss.clients.forEach(client => client.close());
-            wss.close();
-            server.close();
-            process.exit(0);
+            void server.shutdownTaskforce()
+                .then(() => process.exit(0))
+                .catch((error) => {
+                console.error(`[Taskforce] Shutdown failed: ${String(error?.message || error)}`);
+                process.exit(1);
+            });
         };
-        process.on('SIGTERM', shutdown);
-        process.on('SIGINT', shutdown);
+        if (options.manageProcessSignals !== false) {
+            process.on('SIGTERM', shutdown);
+            process.on('SIGINT', shutdown);
+        }
     });
     return server;
 }