@taskforcehq/taskforce 0.3.327 → 0.3.328

package/dist/server/cloudCollectionRead.js

@@ -0,0 +1,120 @@
+import { getRequestPerformanceDiagnostics, runWithRequestPerformanceDiagnostics, } from '../storage/postgresRequestDiagnostics.js';
+import { resolveAppAccessDeniedResponse } from './appAccess.js';
+import { resolveAuthorizedWorkspaceAccess, resolveDisabledAccessError, } from './authorizedWorkspaceAccess.js';
+const ROUTE_BY_OPERATION = {
+    tasks: '/api/taskforce/tasks',
+    archive: '/api/taskforce/archive',
+    deleted: '/api/taskforce/deleted',
+    'planning-bootstrap': '/api/taskforce/planning/bootstrap',
+};
+export function resolveCloudCollectionReadOperation(method, pathname) {
+    if (String(method || 'GET').toUpperCase() !== 'GET')
+        return null;
+    if (pathname === '/api/taskforce/tasks')
+        return 'tasks';
+    if (pathname === '/api/taskforce/archive')
+        return 'archive';
+    if (pathname === '/api/taskforce/deleted' || pathname === '/api/taskforce/trash')
+        return 'deleted';
+    if (pathname === '/api/taskforce/planning/bootstrap')
+        return 'planning-bootstrap';
+    return null;
+}
+function serverTimingMetric(name, durationMs) {
+    return `${name};dur=${Math.max(0, Math.round(durationMs))}`;
+}
+function performanceHeaders(diagnostics, responseBytes, metrics) {
+    const headers = {
+        'Content-Type': 'application/json',
+        'Server-Timing': metrics.map((metric) => serverTimingMetric(metric.name, metric.durationMs)).join(', '),
+    };
+    if (diagnostics) {
+        headers['X-Taskforce-Postgres-Query-Count'] = String(diagnostics.postgresQueryCount);
+        headers['X-Taskforce-Postgres-Worker-Call-Count'] = String(diagnostics.postgresWorkerCallCount);
+        headers['X-Taskforce-Response-Bytes'] = String(responseBytes);
+    }
+    return headers;
+}
+export function executeCloudCollectionRead(core, request) {
+    return runWithRequestPerformanceDiagnostics(request.performanceTrace, () => {
+        const access = resolveAuthorizedWorkspaceAccess(core, request.access, request.requestedWorkspaceId);
+        const workspaceId = String(access.workspaceId || '').trim();
+        const disabledAccessError = resolveDisabledAccessError(access, request.pathname);
+        if (disabledAccessError) {
+            return {
+                statusCode: 403,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ error: disabledAccessError }),
+                workspaceId,
+            };
+        }
+        if (access.authenticated && access.userId && access.userId !== 'anonymous') {
+            const denied = resolveAppAccessDeniedResponse(core.getAccountAccessStatus(access.userId));
+            if (denied) {
+                return {
+                    statusCode: denied.statusCode,
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(denied.body),
+                    workspaceId,
+                };
+            }
+        }
+        const startedAt = performance.now();
+        let data;
+        const planningDiagnostics = {};
+        if (request.operation === 'tasks')
+            data = core.listTasks(workspaceId);
+        else if (request.operation === 'archive')
+            data = core.listArchive(workspaceId);
+        else if (request.operation === 'deleted')
+            data = core.listDeletedTasksReadOnly(workspaceId);
+        else
+            data = core.listPlanningBootstrap(workspaceId, planningDiagnostics);
+        const loadCompletedAt = performance.now();
+        const serializeStartedAt = performance.now();
+        const body = JSON.stringify(data);
+        const serializeDurationMs = performance.now() - serializeStartedAt;
+        const totalDurationMs = performance.now() - startedAt;
+        const responseBytes = Buffer.byteLength(body, 'utf8');
+        const diagnostics = getRequestPerformanceDiagnostics();
+        const metrics = request.operation === 'planning-bootstrap'
+            ? [
+                { name: 'planning-bootstrap', durationMs: totalDurationMs },
+                { name: 'planning-bootstrap-initiatives', durationMs: planningDiagnostics.initiativeLoadMs || 0 },
+                { name: 'planning-bootstrap-workstreams', durationMs: planningDiagnostics.workstreamLoadMs || 0 },
+                { name: 'planning-bootstrap-tasks', durationMs: planningDiagnostics.taskSummaryQueryMs || 0 },
+                { name: 'planning-bootstrap-build', durationMs: planningDiagnostics.taskSummaryBuildMs || 0 },
+                { name: 'planning-bootstrap-json', durationMs: serializeDurationMs },
+            ]
+            : [
+                { name: 'route-total', durationMs: totalDurationMs },
+                { name: 'route-load', durationMs: loadCompletedAt - startedAt },
+                { name: 'route-json', durationMs: serializeDurationMs },
+            ];
+        if (diagnostics) {
+            metrics.push({ name: 'postgres-worker-wait', durationMs: diagnostics.postgresWorkerWaitMs });
+        }
+        return {
+            statusCode: 200,
+            headers: performanceHeaders(diagnostics, responseBytes, metrics),
+            body,
+            workspaceId,
+            performance: {
+                durationMs: totalDurationMs,
+                details: {
+                    responseBytes,
+                    jsonSerializeMs: serializeDurationMs,
+                    ...(diagnostics ? {
+                        postgresQueryCount: diagnostics.postgresQueryCount,
+                        postgresWorkerCallCount: diagnostics.postgresWorkerCallCount,
+                        postgresWorkerWaitMs: Math.round(diagnostics.postgresWorkerWaitMs),
+                    } : {}),
+                    ...(request.operation === 'planning-bootstrap' ? planningDiagnostics : {}),
+                },
+            },
+        };
+    });
+}
+export function cloudCollectionReadRoute(operation) {
+    return ROUTE_BY_OPERATION[operation];
+}

package/dist/server/cloudCollectionReadPool.d.ts

@@ -0,0 +1,52 @@
+import type { CloudCollectionReadRequest, CloudCollectionReadResponse } from './cloudCollectionRead.js';
+export interface CloudCollectionReadPoolOptions {
+    projectRoot: string;
+    tenantId: string;
+    connectionString: string;
+    size?: number;
+    requestTimeoutMs?: number;
+    workerFactory?: () => CloudCollectionReadWorker;
+}
+export interface CloudCollectionReadWorker {
+    postMessage(message: unknown): void;
+    terminate(): Promise<number>;
+    on(event: 'message', listener: (message: CloudCollectionReadWorkerResponse) => void): this;
+    on(event: 'error', listener: (error: unknown) => void): this;
+    on(event: 'exit', listener: (code: number) => void): this;
+}
+export type CloudCollectionReadWorkerResponse = {
+    type: 'ready';
+} | {
+    type: 'result';
+    requestId: number;
+    response: CloudCollectionReadResponse;
+} | {
+    type: 'error';
+    requestId: number;
+    error: string;
+};
+export declare class CloudCollectionReadPool {
+    private readonly slots;
+    private readonly queue;
+    private readonly requestTimeoutMs;
+    private readonly desiredSize;
+    private readonly workerData;
+    private readonly workerFactory;
+    private nextRequestId;
+    private closing;
+    constructor(options: CloudCollectionReadPoolOptions);
+    execute(request: CloudCollectionReadRequest): Promise<CloudCollectionReadResponse>;
+    close(): Promise<void>;
+    private spawnSlot;
+    private handleMessage;
+    private handleWorkerFailure;
+    private ensureSlots;
+    private pump;
+}
+export declare function resolveCloudCollectionReadPoolSize(env?: NodeJS.ProcessEnv): number;
+export declare function shouldUseCloudCollectionReadPool(input: {
+    runtimeMode: 'local' | 'cloud';
+    databaseProvider: 'sqlite' | 'postgres';
+    connectionString?: string;
+    workerCount: number;
+}): boolean;

package/dist/server/cloudCollectionReadPool.js

@@ -0,0 +1,140 @@
+import { Worker } from 'node:worker_threads';
+const DEFAULT_POOL_SIZE = 2;
+const MAX_POOL_SIZE = 8;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+function positiveInteger(value, fallback) {
+    if (!Number.isFinite(value) || Number(value) <= 0)
+        return fallback;
+    return Math.max(1, Math.floor(Number(value)));
+}
+export class CloudCollectionReadPool {
+    slots = [];
+    queue = [];
+    requestTimeoutMs;
+    desiredSize;
+    workerData;
+    workerFactory;
+    nextRequestId = 1;
+    closing = false;
+    constructor(options) {
+        this.requestTimeoutMs = positiveInteger(options.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+        this.workerData = {
+            projectRoot: options.projectRoot,
+            tenantId: options.tenantId,
+            connectionString: options.connectionString,
+        };
+        this.workerFactory = options.workerFactory || (() => new Worker(new URL('./cloudCollectionReadWorker.js', import.meta.url), { workerData: this.workerData }));
+        this.desiredSize = Math.min(MAX_POOL_SIZE, positiveInteger(options.size, DEFAULT_POOL_SIZE));
+    }
+    execute(request) {
+        if (this.closing) {
+            return Promise.reject(new Error('[Taskforce] Cloud collection read pool is closed.'));
+        }
+        this.ensureSlots();
+        return new Promise((resolve, reject) => {
+            this.queue.push({ request, resolve, reject });
+            this.pump();
+        });
+    }
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        const closedError = new Error('[Taskforce] Cloud collection read pool closed before the request completed.');
+        for (const pending of this.queue.splice(0))
+            pending.reject(closedError);
+        await Promise.all(this.slots.splice(0).map(async (slot) => {
+            if (slot.active) {
+                clearTimeout(slot.active.timeout);
+                slot.active.reject(closedError);
+                slot.active = null;
+            }
+            slot.worker.postMessage({ type: 'close' });
+            await slot.worker.terminate();
+        }));
+    }
+    spawnSlot() {
+        if (this.closing)
+            return;
+        const worker = this.workerFactory();
+        const slot = { worker, ready: false, active: null };
+        this.slots.push(slot);
+        worker.on('message', (message) => this.handleMessage(slot, message));
+        worker.on('error', (error) => this.handleWorkerFailure(slot, error instanceof Error ? error : new Error(String(error))));
+        worker.on('exit', (code) => {
+            if (!this.closing && this.slots.includes(slot)) {
+                this.handleWorkerFailure(slot, new Error(`[Taskforce] Cloud collection read worker exited with code ${code}.`));
+            }
+        });
+    }
+    handleMessage(slot, message) {
+        if (message.type === 'ready') {
+            slot.ready = true;
+            this.ensureSlots();
+            this.pump();
+            return;
+        }
+        const active = slot.active;
+        if (!active || active.requestId !== message.requestId)
+            return;
+        clearTimeout(active.timeout);
+        slot.active = null;
+        if (message.type === 'result')
+            active.resolve(message.response);
+        else
+            active.reject(new Error(message.error || '[Taskforce] Cloud collection read worker failed.'));
+        this.pump();
+    }
+    handleWorkerFailure(slot, error) {
+        const slotIndex = this.slots.indexOf(slot);
+        if (slotIndex < 0)
+            return;
+        this.slots.splice(slotIndex, 1);
+        if (slot.active) {
+            clearTimeout(slot.active.timeout);
+            slot.active.reject(error);
+            slot.active = null;
+        }
+        void slot.worker.terminate();
+        if (!this.closing && this.slots.length === 0) {
+            for (const pending of this.queue.splice(0))
+                pending.reject(error);
+        }
+        this.pump();
+    }
+    ensureSlots() {
+        if (this.closing)
+            return;
+        if (this.slots.some((slot) => !slot.ready))
+            return;
+        if (this.slots.length < this.desiredSize)
+            this.spawnSlot();
+    }
+    pump() {
+        if (this.closing || this.queue.length === 0)
+            return;
+        for (const slot of this.slots) {
+            if (!slot.ready || slot.active || this.queue.length === 0)
+                continue;
+            const pending = this.queue.shift();
+            const requestId = this.nextRequestId++;
+            const timeout = setTimeout(() => {
+                this.handleWorkerFailure(slot, new Error(`[Taskforce] Cloud collection read worker timed out after ${this.requestTimeoutMs}ms.`));
+            }, this.requestTimeoutMs);
+            timeout.unref?.();
+            slot.active = { ...pending, requestId, timeout };
+            slot.worker.postMessage({ type: 'execute', requestId, request: pending.request });
+        }
+    }
+}
+export function resolveCloudCollectionReadPoolSize(env = process.env) {
+    if (String(env.TASKFORCE_CLOUD_READ_WORKERS || '').trim() === '0')
+        return 0;
+    return Math.min(MAX_POOL_SIZE, positiveInteger(Number(env.TASKFORCE_CLOUD_READ_WORKERS), DEFAULT_POOL_SIZE));
+}
+export function shouldUseCloudCollectionReadPool(input) {
+    return input.runtimeMode === 'cloud'
+        && input.databaseProvider === 'postgres'
+        && Boolean(String(input.connectionString || '').trim())
+        && input.workerCount > 0;
+}

package/dist/server/cloudCollectionReadWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/cloudCollectionReadWorker.js

@@ -0,0 +1,36 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { TaskforceCore } from '../core/Taskforce.js';
+import { executeCloudCollectionRead, } from './cloudCollectionRead.js';
+if (!parentPort) {
+    throw new Error('[Taskforce] Cloud collection read worker requires a parent port.');
+}
+const config = workerData;
+const core = new TaskforceCore({
+    projectRoot: config.projectRoot,
+    tenantId: config.tenantId,
+    runtimeMode: 'cloud',
+    initializationMode: 'cloud-read-worker',
+    database: {
+        provider: 'postgres',
+        connectionString: config.connectionString,
+    },
+});
+parentPort.on('message', (message) => {
+    if (message.type === 'close') {
+        core.close();
+        parentPort?.close();
+        return;
+    }
+    try {
+        const response = executeCloudCollectionRead(core, message.request);
+        parentPort?.postMessage({ type: 'result', requestId: message.requestId, response });
+    }
+    catch (error) {
+        parentPort?.postMessage({
+            type: 'error',
+            requestId: message.requestId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+});
+parentPort.postMessage({ type: 'ready' });

package/dist/server/index.d.ts

@@ -6,8 +6,8 @@
  */
 import * as http from 'http';
 import { WebSocketServer } from 'ws';
-import { TaskforceCore } from '../core/Taskforce.js';
-import type { RequestAccessContext } from './auth.js';
+export { resolveAuthorizedWorkspaceAccess, resolveDisabledAccessError, isWorkspaceAccessRecoveryRoute, } from './authorizedWorkspaceAccess.js';
+import type { LocalServiceCloudTarget } from '../config/localServiceCloudTarget.js';
 import type { LocalSyncCoordinatorHost } from '../sync/coordinator/localSyncCoordinatorHost.js';
 import type { LocalSyncProcessLock } from '../sync/coordinator/localSyncProcessLock.js';
 import type { LocalDataOwnerPermit } from './localDataOwnerPermit.js';
@@ -25,6 +25,7 @@ export interface StandaloneServerOptions {
         ownerPid: number;
         bootstrapCapability: string;
         ownershipKey: string;
+        cloudTarget: LocalServiceCloudTarget;
     };
 }
 export interface TaskforceStandaloneServer extends http.Server {
@@ -45,17 +46,9 @@ export declare const TASKFORCE_PROXY_ORIGIN_PROTO_HEADER = "x-taskforce-origin-p
 export declare const TASKFORCE_PROXY_ORIGIN_BASE_URL_HEADER = "x-taskforce-origin-base-url";
 export declare const TASKFORCE_PROXY_ORIGIN_RUNTIME_HEADER = "x-taskforce-origin-runtime";
 export declare const TASKFORCE_PROXY_CLOUD_ENVIRONMENT_HEADER = "x-taskforce-cloud-environment";
-interface AuthorizedRequestAccess extends RequestAccessContext {
-    disabled?: boolean;
-    accountDisabled?: boolean;
-    workspaceDisabled?: boolean;
-}
-export declare function isWorkspaceAccessRecoveryRoute(pathname: string): boolean;
-export declare function resolveDisabledAccessError(access: Pick<AuthorizedRequestAccess, 'disabled' | 'accountDisabled' | 'workspaceDisabled'>, pathname: string): string | null;
 export declare function shouldProxyCloudPath(pathname: string): boolean;
 export declare function shouldProxyCloudRequest(url: Pick<URL, 'pathname' | 'searchParams'>, env?: NodeJS.ProcessEnv): boolean;
 export declare function resolveCloudProxyUpstreamBaseUrl(req: http.IncomingMessage, fallbackBaseUrl: string): string;
-export declare function resolveAuthorizedWorkspaceAccess(core: Pick<TaskforceCore, 'resolveUserAccess' | 'getSystemRole'>, access: AuthorizedRequestAccess, requestedWorkspaceId: string): AuthorizedRequestAccess;
 export declare function shouldApplyReadOnlyMutationGuard(methodRaw: string | undefined, pathname: string): boolean;
 export declare function resolveEffectiveRequestUserId(accessUserId: string, explicitUserId: string): string;
 export declare function resolveMaxPayloadBytesForPath(pathname: string, defaultMaxBytes: number): number;
@@ -72,4 +65,3 @@ export declare function ensurePublicPricingAuthExclusion(excludedPaths: string[]
 export declare function ensurePublicSiteConfigAuthExclusion(excludedPaths: string[]): string[];
 export declare function isBillingWebhookPath(pathname: string): boolean;
 export declare function createStandaloneServer(options: StandaloneServerOptions): TaskforceStandaloneServer;
-export {};

package/dist/server/index.js

@@ -14,9 +14,12 @@ 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';
@@ -37,6 +40,8 @@ import { createWorkspaceSyncServerComposition, shutdownWorkspaceSyncServerCompos
 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 = {
@@ -173,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));
 }
@@ -301,31 +291,6 @@ export function resolveCloudProxyUpstreamBaseUrl(req, fallbackBaseUrl) {
         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')
@@ -673,6 +638,20 @@ export function createStandaloneServer(options) {
             },
         } : undefined,
     });
+    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'
@@ -1066,6 +1045,39 @@ export function createStandaloneServer(options) {
                     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;
@@ -1203,6 +1215,7 @@ export function createStandaloneServer(options) {
                     if (serverResult.status === 'rejected') {
                         throw serverResult.reason;
                     }
+                    await cloudCollectionReadPool?.close();
                 },
                 closeCore: () => core.close(),
             });

package/dist/server/localServiceLease.d.ts

@@ -1,3 +1,4 @@
+import { type LocalServiceCloudTarget } from '../config/localServiceCloudTarget.js';
 import { type WindowsAclCommandRunner } from './localServiceWindowsAcl.js';
 export interface LocalServiceDescriptor {
     schemaVersion: 1;
@@ -9,6 +10,7 @@ export interface LocalServiceDescriptor {
     generation: string;
     bootstrapCapability: string;
     publishedAt: string;
+    cloudTarget?: LocalServiceCloudTarget | null;
 }
 export interface LocalServiceLeaseIdentityInput {
     projectRoot: string;
@@ -27,6 +29,7 @@ export interface LocalServiceDescriptorPublication {
     endpoint: string;
     protocolVersion: string;
     appVersion: string;
+    cloudTarget: LocalServiceCloudTarget;
 }
 export interface LocalServiceLease {
     readonly identity: LocalServiceLeaseIdentity;

package/dist/server/localServiceLease.js

@@ -3,6 +3,7 @@ import * as fs from 'fs';
 import * as net from 'net';
 import * as os from 'os';
 import * as path from 'path';
+import { parseLocalServiceCloudTarget, } from '../config/localServiceCloudTarget.js';
 import { resolveLocalSyncProcessLockIdentity } from './localDatabaseIdentity.js';
 import { ensureWindowsUserOnlyDirectoryAcl, } from './localServiceWindowsAcl.js';
 const DESCRIPTOR_SCHEMA_VERSION = 1;
@@ -161,8 +162,14 @@ function parseDescriptor(value, ownershipKey) {
         || typeof value.publishedAt !== 'string') {
         throw new Error('Local service descriptor is invalid.');
     }
+    const cloudTarget = value.cloudTarget == null
+        ? null
+        : parseLocalServiceCloudTarget(value.cloudTarget);
+    if (value.cloudTarget != null && !cloudTarget) {
+        throw new Error('Local service descriptor cloud target is invalid.');
+    }
     assertLoopbackEndpoint(value.endpoint);
-    return value;
+    return { ...value, cloudTarget };
 }
 function readOptionalDescriptor(identity) {
     try {
@@ -363,6 +370,7 @@ export async function acquireLocalServiceLease(input, dependencies = {}) {
                         generation,
                         bootstrapCapability,
                         publishedAt: (dependencies.now?.() || new Date()).toISOString(),
+                        cloudTarget: publication.cloudTarget,
                     };
                     publishJsonFileAtomically(identity.descriptorPath, descriptor, platform);
                     return descriptor;

package/dist/server/routes/documents.d.ts

@@ -8,6 +8,8 @@
  *   POST   /api/taskforce/context-upload/init
  *   POST   /api/taskforce/context-upload/finalize
  *   POST   /api/taskforce/context-upload
+ *   POST   /api/taskforce/context-upload/draft/promote
+ *   POST   /api/taskforce/context-upload/draft/discard
  *   GET    /api/taskforce/context/:filename
  *   GET    /api/taskforce/documents/:assetId/content
  *   GET    /api/taskforce/context-link
@@ -39,7 +41,7 @@ type AssetMetadata = DocumentRegistryEntry & {
     originalFilename?: string | null;
 };
 interface CanonicalReadResult {
-    statusCode: 200 | 302 | 404;
+    statusCode: 200 | 302 | 404 | 409;
     headers?: Record<string, string>;
     body?: Buffer;
 }
@@ -81,6 +83,7 @@ export interface DocumentRouteDependencies {
         workspaceId?: string;
         taskId?: string | null;
         originalName?: string | null;
+        actorRef?: string | null;
     }) => Promise<{
         scan?: {
             verdict?: string;
@@ -110,7 +113,7 @@ export interface DocumentRouteDependencies {
     sanitizeDownloadFilename: (nameRaw: string, fallback?: string) => string;
     contentTypeForExt: (ext: string) => string;
     inferInlineDocumentFromPath: (pathValue: string | null | undefined) => boolean;
-    resolveCanonicalDocumentRead: (params: {
+    resolveCanonicalContentRead: (params: {
         asset: WorkspaceAssetEntry;
         forceDownload: boolean;
         requestedFilename?: string | null;