@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/server/localServiceSessions.js

@@ -0,0 +1,309 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'crypto';
+export const LOCAL_SERVICE_SESSION_IDLE_TTL_MS = 24 * 60 * 60 * 1_000;
+export const LOCAL_SERVICE_SESSION_CAP = 256;
+export const LOCAL_SERVICE_OPERATION_BINDING_CAP = 4_096;
+export const LOCAL_SERVICE_CANCELLATION_BINDING_CAP = 1_024;
+export const LOCAL_SERVICE_CANCELLATION_TOMBSTONE_TTL_MS = 60_000;
+export class LocalServiceSessionError extends Error {
+    statusCode;
+    code;
+    constructor(message, statusCode, code) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+    }
+}
+function digestToken(token) {
+    return createHash('sha256').update(token, 'utf8').digest();
+}
+function publicSession(session) {
+    const { tokenDigest: _tokenDigest, lastUsedAtMs: _lastUsedAtMs, ...result } = session;
+    return { ...result, permissions: [...result.permissions] };
+}
+export class LocalServiceSessionManager {
+    generation;
+    options;
+    sessions = new Map();
+    inFlightBySession = new Map();
+    operationBindings = new Map();
+    cancellationBindings = new Map();
+    cancellationTombstones = new Map();
+    drainWaiters = new Set();
+    lifecycleState = 'accepting';
+    constructor(generation, options = {}) {
+        this.generation = generation;
+        this.options = options;
+    }
+    nowMs() {
+        return this.options.nowMs?.() ?? Date.now();
+    }
+    prune() {
+        const cutoff = this.nowMs() - (this.options.idleTtlMs ?? LOCAL_SERVICE_SESSION_IDLE_TTL_MS);
+        let pruned = 0;
+        for (const [id, session] of this.sessions) {
+            if (session.lastUsedAtMs > cutoff)
+                continue;
+            this.sessions.delete(id);
+            this.removeOperationBindings(id);
+            this.removeCancellationBindings(id);
+            pruned += 1;
+        }
+        return pruned;
+    }
+    create(input, options = {}) {
+        this.prune();
+        if (this.lifecycleState !== 'accepting') {
+            throw new LocalServiceSessionError('Local service is shutting down.', 503, 'SERVICE_QUIESCING');
+        }
+        if (input.generation !== this.generation) {
+            throw new LocalServiceSessionError('Local service generation mismatch.', 409, 'GENERATION_MISMATCH');
+        }
+        if (this.sessions.size >= (this.options.cap ?? LOCAL_SERVICE_SESSION_CAP)) {
+            throw new LocalServiceSessionError('Local service session capacity reached.', 503, 'SESSION_CAPACITY_REACHED');
+        }
+        const connectionInUse = Array.from(this.sessions.values()).some((session) => (session.workspaceId === input.workspaceId
+            && session.clientId === input.clientId
+            && session.connectionInstance === input.connectionInstance));
+        if (connectionInUse) {
+            throw new LocalServiceSessionError('This client connection instance already has an active local service session.', 409, 'CONNECTION_INSTANCE_IN_USE');
+        }
+        const id = this.options.randomId?.() ?? randomUUID();
+        const secret = this.options.randomSecret?.() ?? randomBytes(32).toString('base64url');
+        const token = `${id}.${secret}`;
+        const nowMs = this.nowMs();
+        const now = new Date(nowMs).toISOString();
+        const stored = {
+            ...input,
+            permissions: [...new Set(input.permissions)],
+            id,
+            createdAt: now,
+            lastUsedAt: now,
+            lastUsedAtMs: nowMs,
+            aiProfileId: options.aiProfileId || null,
+            tokenDigest: digestToken(token),
+        };
+        this.sessions.set(id, stored);
+        return { session: publicSession(stored), token };
+    }
+    authenticate(token, options = {}) {
+        this.prune();
+        const separator = token.indexOf('.');
+        const id = separator > 0 ? token.slice(0, separator) : '';
+        const candidate = this.sessions.get(id);
+        const actualDigest = digestToken(token);
+        const expectedDigest = candidate?.tokenDigest ?? Buffer.alloc(actualDigest.length);
+        if (!candidate || !timingSafeEqual(actualDigest, expectedDigest))
+            return null;
+        if (candidate.generation !== this.generation)
+            return null;
+        if (options.touch !== false) {
+            const nowMs = this.nowMs();
+            candidate.lastUsedAtMs = nowMs;
+            candidate.lastUsedAt = new Date(nowMs).toISOString();
+        }
+        return publicSession(candidate);
+    }
+    revoke(id) {
+        const revoked = this.sessions.delete(id);
+        if (revoked)
+            this.removeOperationBindings(id);
+        if (revoked)
+            this.removeCancellationBindings(id);
+        return revoked;
+    }
+    beginRequest(id) {
+        if (this.lifecycleState !== 'accepting') {
+            throw new LocalServiceSessionError('Local service is shutting down.', 503, 'SERVICE_QUIESCING');
+        }
+        if (!this.sessions.has(id)) {
+            throw new LocalServiceSessionError('Local service session not found.', 401, 'SESSION_NOT_FOUND');
+        }
+        this.inFlightBySession.set(id, (this.inFlightBySession.get(id) || 0) + 1);
+    }
+    endRequest(id) {
+        const remaining = Math.max(0, (this.inFlightBySession.get(id) || 0) - 1);
+        if (remaining === 0)
+            this.inFlightBySession.delete(id);
+        else
+            this.inFlightBySession.set(id, remaining);
+        if (this.inFlightCount() === 0) {
+            for (const resolve of this.drainWaiters)
+                resolve();
+            this.drainWaiters.clear();
+        }
+    }
+    inFlightCount() {
+        let count = 0;
+        for (const value of this.inFlightBySession.values())
+            count += value;
+        return count;
+    }
+    state() {
+        return this.lifecycleState;
+    }
+    beginShutdown(mode) {
+        this.prune();
+        if (this.lifecycleState !== 'accepting') {
+            if (mode === 'force') {
+                this.lifecycleState = 'forcing';
+                this.revokeAll();
+                return;
+            }
+            throw new LocalServiceSessionError('Local service is already shutting down.', 409, 'SERVICE_QUIESCING');
+        }
+        if (mode === 'refuse') {
+            if (this.sessions.size > 0 || this.inFlightCount() > 0) {
+                throw new LocalServiceSessionError('Active sessions prevent shutdown.', 409, 'ACTIVE_SESSIONS');
+            }
+            this.lifecycleState = 'draining';
+            return;
+        }
+        this.lifecycleState = mode === 'drain' ? 'draining' : 'forcing';
+        if (mode === 'force') {
+            this.revokeAll();
+        }
+    }
+    cancelDrain() {
+        if (this.lifecycleState === 'draining')
+            this.lifecycleState = 'accepting';
+    }
+    async waitForDrain(timeoutMs) {
+        if (this.inFlightCount() === 0)
+            return true;
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.drainWaiters.delete(onDrained);
+                resolve(value);
+            };
+            const onDrained = () => finish(true);
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            timer.unref?.();
+            this.drainWaiters.add(onDrained);
+        });
+    }
+    revokeAll() {
+        for (const cancel of this.cancellationBindings.values())
+            cancel();
+        this.sessions.clear();
+        this.operationBindings.clear();
+        this.cancellationBindings.clear();
+        this.cancellationTombstones.clear();
+    }
+    registerCancellation(sessionId, correlationId, cancel) {
+        if (!this.sessions.has(sessionId)) {
+            throw new LocalServiceSessionError('Local service session not found.', 401, 'SESSION_NOT_FOUND');
+        }
+        const key = `${sessionId}:${correlationId}`;
+        this.pruneCancellationTombstones();
+        if (!this.cancellationBindings.has(key)
+            && this.cancellationBindings.size >= LOCAL_SERVICE_CANCELLATION_BINDING_CAP) {
+            throw new LocalServiceSessionError('Too many cancellable local service requests.', 429, 'CANCELLATION_CAP_REACHED');
+        }
+        this.cancellationBindings.set(key, cancel);
+        if (this.cancellationTombstones.delete(key))
+            cancel();
+        return () => {
+            if (this.cancellationBindings.get(key) === cancel)
+                this.cancellationBindings.delete(key);
+        };
+    }
+    cancelRequest(sessionId, correlationId) {
+        if (!this.sessions.has(sessionId))
+            return false;
+        this.pruneCancellationTombstones();
+        const key = `${sessionId}:${correlationId}`;
+        const cancel = this.cancellationBindings.get(key);
+        if (cancel) {
+            cancel();
+            return true;
+        }
+        if (this.cancellationTombstones.size >= LOCAL_SERVICE_CANCELLATION_BINDING_CAP) {
+            const oldestKey = this.cancellationTombstones.keys().next().value;
+            if (oldestKey)
+                this.cancellationTombstones.delete(oldestKey);
+        }
+        this.cancellationTombstones.set(key, this.nowMs() + LOCAL_SERVICE_CANCELLATION_TOMBSTONE_TTL_MS);
+        return true;
+    }
+    recordOperation(input) {
+        if (!this.sessions.has(input.sessionId)) {
+            throw new LocalServiceSessionError('Local service session not found.', 401, 'SESSION_NOT_FOUND');
+        }
+        const key = `${input.sessionId}:${input.operationId}`;
+        const existing = this.operationBindings.get(key);
+        if (existing && (existing.mutationKind !== input.mutationKind
+            || existing.payloadFingerprint !== input.payloadFingerprint)) {
+            throw new LocalServiceSessionError('Operation identity conflicts with an earlier payload in this session.', 409, 'OPERATION_IDENTITY_CONFLICT');
+        }
+        if (existing)
+            return existing;
+        if (this.operationBindings.size >= LOCAL_SERVICE_OPERATION_BINDING_CAP) {
+            const oldestKey = this.operationBindings.keys().next().value;
+            if (oldestKey)
+                this.operationBindings.delete(oldestKey);
+        }
+        const binding = { ...input, recordedAt: new Date(this.nowMs()).toISOString() };
+        this.operationBindings.set(key, binding);
+        return binding;
+    }
+    getOperationBinding(sessionId, operationId, expected) {
+        const binding = this.operationBindings.get(`${sessionId}:${operationId}`) || null;
+        if (!binding)
+            return null;
+        if (expected?.mutationKind && expected.mutationKind !== binding.mutationKind)
+            return null;
+        if (expected?.payloadFingerprint && expected.payloadFingerprint !== binding.payloadFingerprint)
+            return null;
+        return { ...binding };
+    }
+    removeOperationBindings(sessionId) {
+        const prefix = `${sessionId}:`;
+        for (const key of this.operationBindings.keys()) {
+            if (key.startsWith(prefix))
+                this.operationBindings.delete(key);
+        }
+    }
+    removeCancellationBindings(sessionId) {
+        const prefix = `${sessionId}:`;
+        for (const [key, cancel] of this.cancellationBindings) {
+            if (!key.startsWith(prefix))
+                continue;
+            this.cancellationBindings.delete(key);
+            cancel();
+        }
+        for (const key of this.cancellationTombstones.keys()) {
+            if (key.startsWith(prefix))
+                this.cancellationTombstones.delete(key);
+        }
+    }
+    pruneCancellationTombstones() {
+        const now = this.nowMs();
+        for (const [key, expiresAt] of this.cancellationTombstones) {
+            if (expiresAt <= now)
+                this.cancellationTombstones.delete(key);
+        }
+    }
+    bindAiProfile(id, profileId) {
+        const session = this.sessions.get(id);
+        if (!session)
+            throw new LocalServiceSessionError('Local service session not found.', 401, 'SESSION_NOT_FOUND');
+        if (session.aiProfileId && session.aiProfileId !== profileId) {
+            throw new LocalServiceSessionError('This local service session is already bound to a different AI profile.', 409, 'AI_PROFILE_BINDING_CONFLICT');
+        }
+        session.aiProfileId = profileId;
+        return publicSession(session);
+    }
+    activeCount() {
+        this.prune();
+        return this.sessions.size;
+    }
+    list() {
+        this.prune();
+        return Array.from(this.sessions.values(), publicSession);
+    }
+}

package/dist/server/localServiceWindowsAcl.d.ts

@@ -0,0 +1,8 @@
+export interface WindowsAclCommandResult {
+    status: number | null;
+    stdout?: string;
+    stderr?: string;
+    error?: Error;
+}
+export type WindowsAclCommandRunner = (executable: string, args: readonly string[]) => WindowsAclCommandResult;
+export declare function ensureWindowsUserOnlyDirectoryAcl(directory: string, runner?: WindowsAclCommandRunner): void;

package/dist/server/localServiceWindowsAcl.js

@@ -0,0 +1,60 @@
+import { spawnSync } from 'child_process';
+import * as path from 'path';
+const WINDOWS_USER_ONLY_DIRECTORY_ACL_SCRIPT = String.raw `
+$ErrorActionPreference = 'Stop'
+$target = $args[0]
+$item = Get-Item -LiteralPath $target -Force
+if (-not $item.PSIsContainer -or (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0)) {
+    throw 'ACL target must be a real directory'
+}
+$userSid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$systemSid = New-Object System.Security.Principal.SecurityIdentifier('S-1-5-18')
+$inheritance = [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+$propagation = [System.Security.AccessControl.PropagationFlags]::None
+$allow = [System.Security.AccessControl.AccessControlType]::Allow
+$rights = [System.Security.AccessControl.FileSystemRights]::FullControl
+$acl = New-Object System.Security.AccessControl.DirectorySecurity
+$acl.SetAccessRuleProtection($true, $false)
+$acl.AddAccessRule((New-Object System.Security.AccessControl.FileSystemAccessRule($userSid, $rights, $inheritance, $propagation, $allow)))
+$acl.AddAccessRule((New-Object System.Security.AccessControl.FileSystemAccessRule($systemSid, $rights, $inheritance, $propagation, $allow)))
+[System.IO.Directory]::SetAccessControl($target, $acl)
+$verified = [System.IO.Directory]::GetAccessControl($target)
+$rules = @($verified.GetAccessRules($true, $false, [System.Security.Principal.SecurityIdentifier]))
+$allowedSids = @($userSid.Value, $systemSid.Value)
+if (-not $verified.AreAccessRulesProtected -or $rules.Count -ne 2) { throw 'ACL verification failed' }
+foreach ($rule in $rules) {
+    if ($rule.IsInherited -or $rule.AccessControlType -ne $allow -or $allowedSids -notcontains $rule.IdentityReference.Value) {
+        throw 'ACL verification failed'
+    }
+}
+`;
+const defaultRunner = (executable, args) => {
+    const result = spawnSync(executable, [...args], {
+        encoding: 'utf8',
+        windowsHide: true,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+        error: result.error,
+    };
+};
+export function ensureWindowsUserOnlyDirectoryAcl(directory, runner = defaultRunner) {
+    if (!path.isAbsolute(directory)) {
+        throw new Error('The local service ACL target must be an absolute directory path.');
+    }
+    const result = runner('powershell.exe', [
+        '-NoLogo',
+        '-NoProfile',
+        '-NonInteractive',
+        '-ExecutionPolicy',
+        'Bypass',
+        '-Command',
+        WINDOWS_USER_ONLY_DIRECTORY_ACL_SCRIPT,
+        directory,
+    ]);
+    if (result.error || result.status !== 0) {
+        throw new Error('Unable to prove the local service directory is restricted to the current user and SYSTEM.');
+    }
+}

package/dist/server/localSyncProcessLockBootstrap.d.ts

@@ -0,0 +1,3 @@
+import { type LocalSyncProcessLock } from '../sync/coordinator/localSyncProcessLock.js';
+export { resolveLocalDatabaseIdentity as resolveLocalSyncDatabaseIdentity } from './localDatabaseIdentity.js';
+export declare function acquireLocalSyncProcessLockForRuntime(projectRoot: string, env?: NodeJS.ProcessEnv, serviceGeneration?: string | null): Promise<LocalSyncProcessLock | undefined>;

package/dist/server/localSyncProcessLockBootstrap.js

@@ -0,0 +1,16 @@
+import { acquireLocalSyncProcessLock } from '../sync/coordinator/localSyncProcessLock.js';
+import { resolveLocalDatabaseIdentity } from './localDatabaseIdentity.js';
+import { resolveRuntimeModeFromEnv } from './runtimeMode.js';
+export { resolveLocalDatabaseIdentity as resolveLocalSyncDatabaseIdentity } from './localDatabaseIdentity.js';
+export async function acquireLocalSyncProcessLockForRuntime(projectRoot, env = process.env, serviceGeneration) {
+    const provider = env.TASKFORCE_DB_PROVIDER === 'postgres' ? 'postgres' : 'sqlite';
+    const runtimeMode = resolveRuntimeModeFromEnv(env, provider);
+    if (runtimeMode !== 'local')
+        return undefined;
+    return acquireLocalSyncProcessLock({
+        projectRoot,
+        databaseIdentity: resolveLocalDatabaseIdentity(projectRoot, provider, env),
+        databaseIdentityKind: provider === 'sqlite' ? 'path' : 'opaque',
+        serviceGeneration,
+    });
+}

package/dist/server/localWorkspaceSyncServerComposition.d.ts

@@ -0,0 +1,59 @@
+import type { TaskforceCore, TaskforceSyncCapable } from '../core/Taskforce.js';
+import type { ResolvedObjectStorageConfig } from '../storage/objectStorage.js';
+import type { LocalSyncProcessLock } from '../sync/coordinator/localSyncProcessLock.js';
+import type { LocalSyncCoordinatorPrincipal, LocalSyncCoordinatorState } from '../sync/coordinator/localSyncCoordinatorTypes.js';
+import type { LocalSyncCoordinatorRouteServices } from '../sync/coordinator/localSyncCoordinatorRouteServices.js';
+import type { WorkspaceSyncCredentialValidation } from '../sync/coordinator/workspaceSyncCredentialBroker.js';
+import { createWorkspaceSyncServerContentRuntime, type WorkspaceSyncServerContentRuntime } from '../sync/engine/workspaceSyncServerContentRuntime.js';
+import { createWorkspaceSyncServerDataServices, type WorkspaceSyncServerDataServices } from '../sync/engine/workspaceSyncServerDataServices.js';
+import { createLocalWorkspaceSyncServerRuntime, type LocalWorkspaceSyncServerRuntime, type LocalWorkspaceSyncServerRuntimeOptions } from './localWorkspaceSyncServerRuntime.js';
+type ServerSyncCore = TaskforceCore & TaskforceSyncCapable;
+interface WorkspaceSyncServerCompositionFactories {
+    createDataServices: typeof createWorkspaceSyncServerDataServices;
+    createContentRuntime: typeof createWorkspaceSyncServerContentRuntime;
+    createRuntime: typeof createLocalWorkspaceSyncServerRuntime;
+}
+export interface WorkspaceSyncServerComposition {
+    serverDataServices: WorkspaceSyncServerDataServices;
+    contentRuntime: WorkspaceSyncServerContentRuntime | null;
+    runtime: LocalWorkspaceSyncServerRuntime | null;
+    routeServices: LocalSyncCoordinatorRouteServices | null;
+    initialState: LocalSyncCoordinatorState | null;
+}
+export interface WorkspaceSyncServerCompositionOptions {
+    core: ServerSyncCore;
+    runtimeMode: 'local' | 'cloud';
+    processLock?: LocalSyncProcessLock;
+    localBasePath: string;
+    resolveObjectStorageConfig(): ResolvedObjectStorageConfig;
+    cloudBaseUrl: string;
+    sessionCookieName: string;
+    validateWorkspaceAccess(workspaceId: string, principal: LocalSyncCoordinatorPrincipal): Promise<void> | void;
+    validateCredential(input: {
+        cookieHeader: string;
+        workspaceId: string;
+    }): Promise<WorkspaceSyncCredentialValidation>;
+    cloudflareAccess?: {
+        clientId: string;
+        clientSecret: string;
+    } | null;
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+    reportInternalError?: LocalWorkspaceSyncServerRuntimeOptions['reportInternalError'];
+    factories?: Partial<WorkspaceSyncServerCompositionFactories>;
+}
+/**
+ * Constructs the process-owned workspace-sync data plane exactly once.
+ *
+ * Cloud and capture-only local processes still share one route data-service
+ * instance, but only the local process holding the coordinator lock receives a
+ * runtime. Starting that runtime is dark: persisted browser-gateway ownership
+ * remains authoritative until an explicit ownership transfer commits.
+ */
+export declare function createWorkspaceSyncServerComposition(options: WorkspaceSyncServerCompositionOptions): WorkspaceSyncServerComposition;
+export declare function shutdownWorkspaceSyncServerComposition(input: {
+    runtime: LocalWorkspaceSyncServerRuntime | null;
+    closeTransports(): Promise<void>;
+    closeCore(): void;
+}): Promise<void>;
+export {};

package/dist/server/localWorkspaceSyncServerComposition.js

@@ -0,0 +1,91 @@
+import { createWorkspaceSyncServerContentRuntime, } from '../sync/engine/workspaceSyncServerContentRuntime.js';
+import { createWorkspaceSyncServerDataServices, } from '../sync/engine/workspaceSyncServerDataServices.js';
+import { createLocalWorkspaceSyncServerRuntime, } from './localWorkspaceSyncServerRuntime.js';
+/**
+ * Constructs the process-owned workspace-sync data plane exactly once.
+ *
+ * Cloud and capture-only local processes still share one route data-service
+ * instance, but only the local process holding the coordinator lock receives a
+ * runtime. Starting that runtime is dark: persisted browser-gateway ownership
+ * remains authoritative until an explicit ownership transfer commits.
+ */
+export function createWorkspaceSyncServerComposition(options) {
+    const now = options.now || (() => new Date());
+    const factories = {
+        createDataServices: options.factories?.createDataServices
+            || createWorkspaceSyncServerDataServices,
+        createContentRuntime: options.factories?.createContentRuntime
+            || createWorkspaceSyncServerContentRuntime,
+        createRuntime: options.factories?.createRuntime
+            || createLocalWorkspaceSyncServerRuntime,
+    };
+    const serverDataServices = factories.createDataServices({
+        core: options.core,
+        resolveObjectStorageConfig: options.resolveObjectStorageConfig,
+        now,
+    });
+    if (options.runtimeMode !== 'local'
+        || !options.processLock?.owned) {
+        return {
+            serverDataServices,
+            contentRuntime: null,
+            runtime: null,
+            routeServices: null,
+            initialState: null,
+        };
+    }
+    if (!serverDataServices.contentVersionStore) {
+        throw new Error('The local workspace sync runtime requires database-backed content services.');
+    }
+    const contentRuntime = factories.createContentRuntime({
+        contentVersionStore: serverDataServices.contentVersionStore,
+        localBasePath: options.localBasePath,
+        getObjectStorageClient: serverDataServices.getObjectStorageClient,
+        now: () => now().toISOString(),
+    });
+    serverDataServices.configureContentRuntime(contentRuntime);
+    const runtime = factories.createRuntime({
+        core: options.core,
+        processLock: options.processLock,
+        serverDataServices,
+        contentRuntime,
+        cloudBaseUrl: options.cloudBaseUrl,
+        sessionCookieName: options.sessionCookieName,
+        validateWorkspaceAccess: options.validateWorkspaceAccess,
+        validateCredential: options.validateCredential,
+        cloudflareAccess: options.cloudflareAccess,
+        env: options.env,
+        now,
+        reportInternalError: options.reportInternalError,
+    });
+    const initialState = runtime.start();
+    return {
+        serverDataServices,
+        contentRuntime,
+        runtime,
+        routeServices: runtime.routeServices,
+        initialState,
+    };
+}
+export async function shutdownWorkspaceSyncServerComposition(input) {
+    // shutdown() closes coordinator and outbox intake synchronously before its
+    // first await. Starting transport shutdown immediately afterward prevents
+    // new HTTP work while both existing requests and sync work drain.
+    const runtimeShutdown = input.runtime?.shutdown() || Promise.resolve();
+    const transportShutdown = input.closeTransports();
+    const [runtimeResult, transportResult] = await Promise.allSettled([
+        runtimeShutdown,
+        transportShutdown,
+    ]);
+    if (runtimeResult.status === 'rejected') {
+        if (transportResult.status === 'rejected') {
+            throw new AggregateError([runtimeResult.reason, transportResult.reason], 'Workspace sync runtime and server transport shutdown both failed.');
+        }
+        throw runtimeResult.reason;
+    }
+    if (transportResult.status === 'rejected') {
+        throw transportResult.reason;
+    }
+    input.closeCore();
+    await input.runtime?.releaseProcessLock();
+}

package/dist/server/localWorkspaceSyncServerRuntime.d.ts

@@ -0,0 +1,119 @@
+import type { TaskforceCore, TaskforceSyncCapable } from '../core/Taskforce.js';
+import { LocalSyncCoordinatorHost } from '../sync/coordinator/localSyncCoordinatorHost.js';
+import { LocalSyncCoordinatorStore } from '../sync/coordinator/localSyncCoordinatorStore.js';
+import { LocalSyncDispatchTracker } from '../sync/coordinator/localSyncDispatchTracker.js';
+import { LocalSyncExecutionPermitStore } from '../sync/coordinator/localSyncExecutionPermitStore.js';
+import type { LocalSyncProcessLock } from '../sync/coordinator/localSyncProcessLock.js';
+import type { LocalSyncCoordinatorPrincipal, LocalSyncCoordinatorState, LocalSyncCoordinatorWakeSource } from '../sync/coordinator/localSyncCoordinatorTypes.js';
+import type { LocalSyncCoordinatorRouteServices } from '../sync/coordinator/localSyncCoordinatorRouteServices.js';
+import { LocalWorkspaceSyncRunnerStateStore } from '../sync/coordinator/localWorkspaceSyncRunnerState.js';
+import { WorkspaceSyncCredentialBroker, type WorkspaceSyncCredentialSnapshot, type WorkspaceSyncCredentialValidation } from '../sync/coordinator/workspaceSyncCredentialBroker.js';
+import { WorkspaceSyncTransportGateway } from '../sync/coordinator/workspaceSyncTransportGateway.js';
+import type { WorkspaceSyncServerContentRuntime } from '../sync/engine/workspaceSyncServerContentRuntime.js';
+import type { WorkspaceSyncServerDataServices } from '../sync/engine/workspaceSyncServerDataServices.js';
+type ServerSyncCore = TaskforceCore & TaskforceSyncCapable;
+export interface LocalWorkspaceSyncServerRuntimeOptions {
+    core: ServerSyncCore;
+    processLock: LocalSyncProcessLock;
+    serverDataServices: WorkspaceSyncServerDataServices;
+    contentRuntime: WorkspaceSyncServerContentRuntime;
+    cloudBaseUrl: string;
+    sessionCookieName: string;
+    validateWorkspaceAccess(workspaceId: string, principal: LocalSyncCoordinatorPrincipal): Promise<void> | void;
+    validateCredential(input: {
+        cookieHeader: string;
+        workspaceId: string;
+    }): Promise<WorkspaceSyncCredentialValidation>;
+    cloudflareAccess?: {
+        clientId: string;
+        clientSecret: string;
+    } | null;
+    fetchImpl?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+    shutdownGraceMs?: number;
+    periodicWakeMs?: number;
+    outboxDrainBudgetMs?: number;
+    migrationOutboxDrainBudgetMs?: number;
+    setTimer?: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+    reportInternalError?: (error: unknown, source: string) => void;
+}
+export declare function isLocalSyncServerOwnershipTransferEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Dark composition capsule for server-owned local workspace synchronization.
+ *
+ * Construction and start retain browser-gateway ownership. Only the existing
+ * generation-fenced ownership lifecycle can prepare and synchronously activate
+ * a server runner. Production startup constructs this runtime only in the
+ * process holding the local sync lock; server ownership remains fenced until
+ * the activation phase explicitly enables ownership transfer.
+ */
+export declare class LocalWorkspaceSyncServerRuntime {
+    private readonly options;
+    readonly coordinatorStore: LocalSyncCoordinatorStore;
+    readonly permitStore: LocalSyncExecutionPermitStore;
+    readonly credentialBroker: WorkspaceSyncCredentialBroker;
+    readonly transportGateway: WorkspaceSyncTransportGateway;
+    readonly dispatchTracker: LocalSyncDispatchTracker;
+    readonly runnerStateStore: LocalWorkspaceSyncRunnerStateStore;
+    readonly host: LocalSyncCoordinatorHost;
+    readonly routeServices: LocalSyncCoordinatorRouteServices;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private ownershipDrain;
+    private runnerBundle;
+    private runnerInitializationPromise;
+    private periodicWakeTimer;
+    private wakePromise;
+    private readonly pendingWakeSources;
+    private readonly suppressedRealtimeEventIds;
+    private readonly suppressedRealtimeEventIdQueue;
+    private readonly localRealtimeEventHighWatermarks;
+    private pendingRemoteHintObservedAt;
+    private pendingCommand;
+    private offMutationWake;
+    private offRealtimeWakeSuppression;
+    private ordinaryWakeEpoch;
+    private shuttingDown;
+    private shutdownPromise;
+    constructor(options: LocalWorkspaceSyncServerRuntimeOptions);
+    start(): LocalSyncCoordinatorState;
+    bindCredential(input: {
+        cookieHeader: string | undefined;
+        workspaceId: string;
+        coordinatorGeneration: number;
+        allowPrincipalRebind?: boolean;
+    }): Promise<WorkspaceSyncCredentialSnapshot>;
+    private onCredentialBound;
+    private resumeServerAfterAuthenticatedRestart;
+    private reconcileSettledDispatchRecovery;
+    private ensureActiveRunnerBundle;
+    private ensurePreparedRunnerBundle;
+    private ensureRunnerBundle;
+    requestWake(source: LocalSyncCoordinatorWakeSource, expectedScope?: {
+        workspaceId: string;
+        coordinatorGeneration: number;
+    }, realtimeEventIds?: readonly string[]): boolean;
+    private consumeSuppressedRealtimeEventId;
+    private beginWakeLoop;
+    private runWakeCycle;
+    private runFairnessPull;
+    shutdown(graceMs?: number): Promise<void>;
+    private awaitRunnerInitialization;
+    releaseProcessLock(): Promise<void>;
+    private createOwnershipLifecycle;
+    private createRunnerBundle;
+    private onCommandAccepted;
+    private startPeriodicWake;
+    private stopPeriodicWake;
+    private requireBundle;
+    private drainOutbox;
+    private drainMigrationOutbox;
+    private promotePendingRemoteHint;
+    private contextFor;
+    private assertCompositionInputs;
+}
+export declare function createLocalWorkspaceSyncServerRuntime(options: LocalWorkspaceSyncServerRuntimeOptions): LocalWorkspaceSyncServerRuntime;
+export {};