@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/sync/coordinator/localSyncCoordinatorStore.js

@@ -0,0 +1,1039 @@
+import { LOCAL_SYNC_COORDINATOR_ID, LocalSyncCoordinatorError, } from './localSyncCoordinatorTypes.js';
+const RECONCILE_COMMAND_TYPES = new Set(['Sync', 'Retry']);
+export const LOCAL_SYNC_COMMAND_RETENTION_MIN_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export const LOCAL_SYNC_COMMAND_RETENTION_SOFT_LIMIT = 1_000;
+export const LOCAL_SYNC_COMMAND_RETENTION_DELETE_BATCH = 250;
+function coalescingTypes(type) {
+    if (RECONCILE_COMMAND_TYPES.has(type))
+        return ['Sync', 'Retry'];
+    return [type];
+}
+function supersededTypes(type) {
+    return type === 'Repair' || type === 'DisableSync'
+        ? ['Sync', 'Retry']
+        : [];
+}
+function isRunnerCommandType(type) {
+    return ['EnableSync', 'DisableSync', 'Sync', 'Retry', 'Repair'].includes(type);
+}
+function parseJson(value) {
+    if (!value)
+        return null;
+    return JSON.parse(value);
+}
+function parsePrincipal(value) {
+    const parsed = parseJson(value);
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const candidate = parsed;
+    if (!candidate.userId || !candidate.tenantId)
+        return null;
+    return { userId: candidate.userId, tenantId: candidate.tenantId };
+}
+function collectCommandReferences(value, target) {
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectCommandReferences(item, target);
+        return;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (['commandId', 'leaderCommandId', 'supersedingCommandId'].includes(key)
+            && typeof item === 'string'
+            && item.trim()) {
+            target.add(item.trim());
+        }
+        else if (item && typeof item === 'object') {
+            collectCommandReferences(item, target);
+        }
+    }
+}
+function parseTerminalTransferRecord(value) {
+    const parsed = parseJson(value);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const candidate = parsed;
+    if (typeof candidate.commandId !== 'string'
+        || !['succeeded', 'failed'].includes(String(candidate.status))
+        || !['server', 'browser-gateway'].includes(String(candidate.sourceMode))
+        || !['server', 'browser-gateway'].includes(String(candidate.targetMode))
+        || !Number.isInteger(candidate.sourceGeneration)
+        || !Number.isInteger(candidate.targetGeneration)
+        || typeof candidate.completedAt !== 'string'
+        || (candidate.errorCode !== null && typeof candidate.errorCode !== 'string')
+        || (candidate.errorPhase !== null
+            && ![
+                'preparing',
+                'draining',
+                'generation-advanced',
+                'starting-target',
+                'stopping-source',
+                'committing',
+            ].includes(String(candidate.errorPhase)))) {
+        return null;
+    }
+    return {
+        commandId: candidate.commandId,
+        status: candidate.status,
+        sourceMode: candidate.sourceMode,
+        targetMode: candidate.targetMode,
+        sourceGeneration: candidate.sourceGeneration,
+        targetGeneration: candidate.targetGeneration,
+        completedAt: candidate.completedAt,
+        errorCode: candidate.errorCode,
+        errorPhase: candidate.errorPhase,
+    };
+}
+function mapState(row) {
+    if (row.desired_ownership_mode !== 'server'
+        && row.desired_ownership_mode !== 'browser-gateway') {
+        throw new LocalSyncCoordinatorError('The local sync coordinator has an invalid desired ownership mode.', 'SYNC_COORDINATOR_STATE_CORRUPT');
+    }
+    return {
+        activeWorkspaceId: row.active_workspace_id || null,
+        coordinatorGeneration: Number(row.coordinator_generation || 0),
+        localDataVersion: Number(row.local_data_version || 0),
+        ownershipMode: row.ownership_mode || 'stopped',
+        desiredOwnershipMode: row.desired_ownership_mode,
+        transitionState: row.transition_state || 'idle',
+        acceptedSwitchCommandId: row.accepted_switch_command_id || null,
+        targetWorkspaceId: row.target_workspace_id || null,
+        requestedBy: parsePrincipal(row.requested_by_json),
+        terminalSwitchResult: parseJson(row.terminal_switch_result_json),
+        terminalTransferResult: parseTerminalTransferRecord(row.terminal_transfer_result_json),
+        acceptedTransferCommandId: row.accepted_transfer_command_id || null,
+        transferTargetMode: row.transfer_target_mode || null,
+        transferPhase: row.transfer_phase || null,
+        transferVersion: row.transfer_version == null ? null : Number(row.transfer_version),
+        updatedAt: String(row.updated_at || ''),
+    };
+}
+function mapCommand(row) {
+    return {
+        commandId: String(row.command_id || ''),
+        workspaceId: row.workspace_id || null,
+        expectedCoordinatorGeneration: Number(row.expected_coordinator_generation || 0),
+        type: row.command_type || 'Sync',
+        version: Number(row.command_version || 1),
+        args: parseJson(row.args_json),
+        canonicalFingerprint: String(row.canonical_fingerprint || ''),
+        requestedBy: parsePrincipal(row.requested_by_json) || { userId: '', tenantId: '' },
+        requestedAt: String(row.requested_at || ''),
+        status: row.status || 'failed',
+        startedAt: row.started_at || null,
+        completedAt: row.completed_at || null,
+        result: parseJson(row.result_json),
+        errorCode: row.error_code || null,
+        errorMessage: row.error_message || null,
+        updatedAt: String(row.updated_at || ''),
+    };
+}
+function buildTerminalTransferRecord(input) {
+    const { acceptedTransferCommandId, transferTargetMode, transferPhase, coordinatorGeneration, } = input.state;
+    if (!acceptedTransferCommandId || !transferTargetMode || !transferPhase) {
+        throw new LocalSyncCoordinatorError('The ownership transfer is missing terminal evidence coordinates.', 'SYNC_COORDINATOR_COMMAND_INVALID');
+    }
+    const generationAdvanced = !['preparing', 'draining'].includes(transferPhase);
+    const sourceGeneration = generationAdvanced
+        ? coordinatorGeneration - 1
+        : coordinatorGeneration;
+    return {
+        commandId: acceptedTransferCommandId,
+        status: input.status,
+        sourceMode: transferTargetMode === 'server' ? 'browser-gateway' : 'server',
+        targetMode: transferTargetMode,
+        sourceGeneration,
+        targetGeneration: sourceGeneration + 1,
+        completedAt: input.completedAt,
+        errorCode: input.errorCode ?? null,
+        errorPhase: input.status === 'failed' ? transferPhase : null,
+    };
+}
+export class LocalSyncCoordinatorStore {
+    db;
+    now;
+    constructor(db, now = () => new Date().toISOString()) {
+        this.db = db;
+        this.now = now;
+    }
+    readOrCreateState() {
+        const existing = this.db.prepare(`
+            SELECT *
+            FROM local_sync_coordinator_state
+            WHERE coordinator_id = ?
+        `).get(LOCAL_SYNC_COORDINATOR_ID);
+        if (existing)
+            return mapState(existing);
+        const updatedAt = this.now();
+        this.db.prepare(`
+            INSERT INTO local_sync_coordinator_state (
+                coordinator_id, active_workspace_id, coordinator_generation,
+                ownership_mode, desired_ownership_mode, transition_state, updated_at
+            ) VALUES (?, NULL, 0, 'stopped', 'browser-gateway', 'idle', ?)
+            ON CONFLICT (coordinator_id) DO NOTHING
+        `).run(LOCAL_SYNC_COORDINATOR_ID, updatedAt);
+        return mapState(this.db.prepare(`
+            SELECT *
+            FROM local_sync_coordinator_state
+            WHERE coordinator_id = ?
+        `).get(LOCAL_SYNC_COORDINATOR_ID));
+    }
+    /**
+     * Advances the browser-visible data version after a committed local apply.
+     *
+     * This method deliberately does not open its own transaction. Apply callers
+     * must invoke it inside the same database transaction as the local writes so
+     * the version cannot become visible unless those writes commit.
+     */
+    advanceLocalDataVersion(input) {
+        const result = this.db.prepare(`
+            UPDATE local_sync_coordinator_state
+            SET local_data_version = local_data_version + 1,
+                updated_at = ?
+            WHERE coordinator_id = ?
+              AND active_workspace_id = ?
+              AND coordinator_generation = ?
+        `).run(this.now(), LOCAL_SYNC_COORDINATOR_ID, input.workspaceId, input.expectedCoordinatorGeneration);
+        if (Number(result.changes || 0) === 1) {
+            return this.readOrCreateState().localDataVersion;
+        }
+        const state = this.readOrCreateState();
+        if (state.coordinatorGeneration !== input.expectedCoordinatorGeneration) {
+            throw new LocalSyncCoordinatorError(`Coordinator generation ${input.expectedCoordinatorGeneration} is stale; current generation is ${state.coordinatorGeneration}.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        throw new LocalSyncCoordinatorError(`Workspace ${input.workspaceId} is not the active local sync workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+    }
+    setLifecycleMode(ownershipMode, transitionState) {
+        this.db.prepare(`
+            UPDATE local_sync_coordinator_state
+            SET ownership_mode = ?, transition_state = ?, updated_at = ?
+            WHERE coordinator_id = ?
+        `).run(ownershipMode, transitionState, this.now(), LOCAL_SYNC_COORDINATOR_ID);
+        return this.readOrCreateState();
+    }
+    resumeBrowserGatewayAfterAuthenticatedRestart(input) {
+        return this.resumeDesiredOwnerAfterAuthenticatedRestart({
+            ...input,
+            targetMode: 'browser-gateway',
+        });
+    }
+    resumeServerAfterAuthenticatedRestart(input, activateCommittedOwner) {
+        return this.resumeDesiredOwnerAfterAuthenticatedRestart({
+            ...input,
+            targetMode: 'server',
+        }, activateCommittedOwner);
+    }
+    resumeDesiredOwnerAfterAuthenticatedRestart(input, activateCommittedOwner) {
+        return this.db.transaction(() => {
+            const state = this.readOrCreateState();
+            if (state.coordinatorGeneration !== input.expectedCoordinatorGeneration) {
+                throw new LocalSyncCoordinatorError(`Coordinator generation ${input.expectedCoordinatorGeneration} is stale; current generation is ${state.coordinatorGeneration}.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            if (state.activeWorkspaceId !== input.workspaceId) {
+                throw new LocalSyncCoordinatorError(`Workspace ${input.workspaceId} is not the active local sync workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+            }
+            if (state.ownershipMode === input.targetMode
+                && state.transitionState === 'idle') {
+                return state;
+            }
+            if (state.ownershipMode !== 'stopped'
+                || state.transitionState !== 'idle'
+                || state.desiredOwnershipMode !== input.targetMode) {
+                throw new LocalSyncCoordinatorError('The local sync coordinator cannot resume the requested owner from its current state.', 'SYNC_COORDINATOR_COMMAND_INVALID');
+            }
+            const result = this.db.prepare(`
+                UPDATE local_sync_coordinator_state
+                SET ownership_mode = ?, updated_at = ?
+                WHERE coordinator_id = ?
+                  AND active_workspace_id = ?
+                  AND coordinator_generation = ?
+                  AND ownership_mode = 'stopped'
+                  AND desired_ownership_mode = ?
+                  AND transition_state = 'idle'
+            `).run(input.targetMode, this.now(), LOCAL_SYNC_COORDINATOR_ID, input.workspaceId, input.expectedCoordinatorGeneration, input.targetMode);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncCoordinatorError('The local sync coordinator changed while restart ownership was resuming.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            const resumed = this.readOrCreateState();
+            const activationResult = activateCommittedOwner?.(resumed);
+            if (activationResult
+                && (typeof activationResult === 'object'
+                    || typeof activationResult === 'function')
+                && typeof activationResult.then === 'function') {
+                throw new LocalSyncCoordinatorError('Restart ownership activation must complete synchronously inside the coordinator transaction.', 'SYNC_COORDINATOR_COMMAND_INVALID');
+            }
+            return resumed;
+        })();
+    }
+    acceptCommand(envelope, options = {}) {
+        const accepted = this.db.transaction(() => {
+            const admissionState = isRunnerCommandType(envelope.type)
+                ? (() => {
+                    this.readOrCreateState();
+                    return mapState(this.db.prepare(`
+                        SELECT *
+                        FROM local_sync_coordinator_state
+                        WHERE coordinator_id = ?
+                        ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+                    `).get(LOCAL_SYNC_COORDINATOR_ID));
+                })()
+                : null;
+            const existing = this.readCommand(envelope.commandId);
+            if (existing) {
+                if (existing.canonicalFingerprint !== envelope.canonicalFingerprint) {
+                    throw new LocalSyncCoordinatorError(`Coordinator command ${envelope.commandId} was reused with different input.`, 'SYNC_COORDINATOR_COMMAND_IDENTITY_CONFLICT');
+                }
+                return { record: existing, replayed: true };
+            }
+            if (options.requireActiveWorkspace) {
+                const state = admissionState || this.readOrCreateState();
+                if (state.coordinatorGeneration !== envelope.expectedCoordinatorGeneration
+                    || state.transitionState !== 'idle'
+                    || !['browser-gateway', 'server'].includes(state.ownershipMode)) {
+                    throw new LocalSyncCoordinatorError(`Coordinator generation ${envelope.expectedCoordinatorGeneration} is stale; current generation is ${state.coordinatorGeneration}.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+                }
+                if (!envelope.workspaceId || state.activeWorkspaceId !== envelope.workspaceId) {
+                    throw new LocalSyncCoordinatorError(`Workspace ${envelope.workspaceId || '(none)'} is not the active local sync workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+                }
+                if (options.requireServerOwnership && state.ownershipMode !== 'server') {
+                    throw new LocalSyncCoordinatorError('Runner commands require active server ownership.', 'SYNC_COORDINATOR_COMMAND_INVALID');
+                }
+            }
+            if (options.requireWorkspaceSwitchSource) {
+                const expectedActiveWorkspaceId = options.expectedActiveWorkspaceId ?? null;
+                const state = this.readOrCreateState();
+                if (state.coordinatorGeneration !== envelope.expectedCoordinatorGeneration
+                    || state.transitionState !== 'idle'
+                    || !['browser-gateway', 'server'].includes(state.ownershipMode)) {
+                    throw new LocalSyncCoordinatorError(`Coordinator generation ${envelope.expectedCoordinatorGeneration} is stale; current generation is ${state.coordinatorGeneration}.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+                }
+                if (envelope.workspaceId !== expectedActiveWorkspaceId
+                    || state.activeWorkspaceId !== expectedActiveWorkspaceId) {
+                    throw new LocalSyncCoordinatorError(`Workspace ${expectedActiveWorkspaceId || '(none)'} is not the active local sync workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+                }
+            }
+            if (isRunnerCommandType(envelope.type)) {
+                const activeCommands = this.db.prepare(`
+                    SELECT *
+                    FROM local_sync_coordinator_commands
+                    WHERE workspace_id = ?
+                      AND expected_coordinator_generation = ?
+                      AND command_type IN ('EnableSync', 'DisableSync', 'Sync', 'Retry', 'Repair')
+                      AND status IN ('accepted', 'running')
+                    ORDER BY requested_at ASC, command_id ASC
+                `).all(envelope.workspaceId, envelope.expectedCoordinatorGeneration).map(mapCommand);
+                const coalescingCommandTypes = new Set(coalescingTypes(envelope.type));
+                const leader = activeCommands.find((command) => (coalescingCommandTypes.has(command.type)));
+                const at = this.now();
+                const status = leader ? 'superseded' : 'accepted';
+                const result = leader
+                    ? {
+                        disposition: 'coalesced',
+                        leaderCommandId: leader.commandId,
+                    }
+                    : null;
+                this.db.prepare(`
+                    INSERT INTO local_sync_coordinator_commands (
+                        command_id, workspace_id, expected_coordinator_generation,
+                        command_type, command_version, args_json, canonical_fingerprint,
+                        requested_by_json, requested_at, status, completed_at,
+                        result_json, updated_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                `).run(envelope.commandId, envelope.workspaceId, envelope.expectedCoordinatorGeneration, envelope.type, envelope.version, JSON.stringify(envelope.args ?? null), envelope.canonicalFingerprint, JSON.stringify(envelope.requestedBy), envelope.requestedAt, status, leader ? at : null, result ? JSON.stringify(result) : null, at);
+                const typesToSupersede = supersededTypes(envelope.type);
+                if (typesToSupersede.length > 0) {
+                    const supersedingCommandId = leader?.commandId || envelope.commandId;
+                    const reason = envelope.type === 'DisableSync'
+                        ? 'sync-disabled-before-reconcile'
+                        : 'repair-replaces-reconcile';
+                    this.db.prepare(`
+                        UPDATE local_sync_coordinator_commands
+                        SET status = 'superseded',
+                            completed_at = ?,
+                            result_json = ?,
+                            error_code = NULL,
+                            error_message = NULL,
+                            updated_at = ?
+                        WHERE workspace_id = ?
+                          AND expected_coordinator_generation = ?
+                          AND command_type IN ('Sync', 'Retry')
+                          AND status = 'accepted'
+                    `).run(at, JSON.stringify({
+                        disposition: 'superseded',
+                        supersedingCommandId,
+                        reason,
+                    }), at, envelope.workspaceId, envelope.expectedCoordinatorGeneration);
+                }
+                return { record: this.readCommand(envelope.commandId), replayed: false };
+            }
+            this.db.prepare(`
+                INSERT INTO local_sync_coordinator_commands (
+                    command_id, workspace_id, expected_coordinator_generation,
+                    command_type, command_version, args_json, canonical_fingerprint,
+                    requested_by_json, requested_at, status, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'accepted', ?)
+            `).run(envelope.commandId, envelope.workspaceId, envelope.expectedCoordinatorGeneration, envelope.type, envelope.version, JSON.stringify(envelope.args ?? null), envelope.canonicalFingerprint, JSON.stringify(envelope.requestedBy), envelope.requestedAt, this.now());
+            return { record: this.readCommand(envelope.commandId), replayed: false };
+        })();
+        this.pruneTerminalCommands();
+        return accepted;
+    }
+    readCommand(commandId) {
+        const row = this.db.prepare(`
+            SELECT *
+            FROM local_sync_coordinator_commands
+            WHERE command_id = ?
+        `).get(commandId);
+        return row ? mapCommand(row) : null;
+    }
+    listAcceptedRunnerCommands(input) {
+        return this.db.prepare(`
+            SELECT *
+            FROM local_sync_coordinator_commands
+            WHERE workspace_id = ?
+              AND expected_coordinator_generation = ?
+              AND command_type IN ('EnableSync', 'DisableSync', 'Sync', 'Retry', 'Repair')
+              AND status = 'accepted'
+            ORDER BY
+                CASE WHEN command_type = 'DisableSync' THEN 0 ELSE 1 END,
+                requested_at ASC,
+                command_id ASC
+        `).all(input.workspaceId, input.coordinatorGeneration).map(mapCommand);
+    }
+    claimNextRunnerCommand(input) {
+        return this.db.transaction(() => {
+            this.readOrCreateState();
+            const state = mapState(this.db.prepare(`
+                SELECT *
+                FROM local_sync_coordinator_state
+                WHERE coordinator_id = ?
+                ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+            `).get(LOCAL_SYNC_COORDINATOR_ID));
+            if (state.activeWorkspaceId !== input.workspaceId
+                || state.coordinatorGeneration !== input.coordinatorGeneration
+                || state.ownershipMode !== 'server'
+                || state.transitionState !== 'idle') {
+                throw new LocalSyncCoordinatorError('The runner command execution fence is stale or server ownership is inactive.', state.coordinatorGeneration !== input.coordinatorGeneration
+                    ? 'SYNC_COORDINATOR_STALE_GENERATION'
+                    : 'SYNC_COORDINATOR_COMMAND_INVALID');
+            }
+            const row = this.db.prepare(`
+                SELECT *
+                FROM local_sync_coordinator_commands
+                WHERE workspace_id = ?
+                  AND expected_coordinator_generation = ?
+                  AND command_type IN ('EnableSync', 'DisableSync', 'Sync', 'Retry', 'Repair')
+                  AND status = 'accepted'
+                  AND (? = 1 OR command_type IN ('EnableSync', 'DisableSync'))
+                ORDER BY
+                    CASE WHEN command_type = 'DisableSync' THEN 0 ELSE 1 END,
+                    requested_at ASC,
+                    command_id ASC
+                LIMIT 1
+                ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+            `).get(input.workspaceId, input.coordinatorGeneration, input.cloudCapabilityAvailable ? 1 : 0);
+            if (!row)
+                return null;
+            const command = mapCommand(row);
+            const at = this.now();
+            const result = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'running', started_at = COALESCE(started_at, ?), updated_at = ?
+                WHERE command_id = ? AND status = 'accepted'
+            `).run(at, at, command.commandId);
+            return Number(result?.changes || 0) === 1
+                ? this.readCommand(command.commandId)
+                : null;
+        })();
+    }
+    claimCommandForExecution(input) {
+        return this.db.transaction(() => {
+            this.readOrCreateState();
+            const state = mapState(this.db.prepare(`
+                SELECT *
+                FROM local_sync_coordinator_state
+                WHERE coordinator_id = ?
+                ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+            `).get(LOCAL_SYNC_COORDINATOR_ID));
+            if (state.activeWorkspaceId !== input.workspaceId
+                || state.coordinatorGeneration !== input.coordinatorGeneration
+                || state.ownershipMode !== 'server'
+                || state.transitionState !== 'idle') {
+                throw new LocalSyncCoordinatorError('The runner command execution fence is stale or server ownership is inactive.', state.coordinatorGeneration !== input.coordinatorGeneration
+                    ? 'SYNC_COORDINATOR_STALE_GENERATION'
+                    : 'SYNC_COORDINATOR_COMMAND_INVALID');
+            }
+            const at = this.now();
+            const result = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'running', started_at = COALESCE(started_at, ?), updated_at = ?
+                WHERE command_id = ?
+                  AND workspace_id = ?
+                  AND expected_coordinator_generation = ?
+                  AND command_type IN ('EnableSync', 'DisableSync', 'Sync', 'Retry', 'Repair')
+                  AND status = 'accepted'
+            `).run(at, at, input.commandId, input.workspaceId, input.coordinatorGeneration);
+            return {
+                record: this.readCommand(input.commandId),
+                claimed: Number(result?.changes || 0) === 1,
+            };
+        })();
+    }
+    recoverRunnerCommandsForRecreation(input) {
+        return this.db.transaction(() => {
+            this.readOrCreateState();
+            const state = mapState(this.db.prepare(`
+                SELECT *
+                FROM local_sync_coordinator_state
+                WHERE coordinator_id = ?
+                ${this.db.provider === 'postgres' ? 'FOR UPDATE' : ''}
+            `).get(LOCAL_SYNC_COORDINATOR_ID));
+            if (state.activeWorkspaceId !== input.workspaceId
+                || state.coordinatorGeneration !== input.coordinatorGeneration
+                || state.ownershipMode !== 'server'
+                || state.transitionState !== 'idle') {
+                throw new LocalSyncCoordinatorError('Runner command recovery requires the exact active server generation.', state.coordinatorGeneration !== input.coordinatorGeneration
+                    ? 'SYNC_COORDINATOR_STALE_GENERATION'
+                    : 'SYNC_COORDINATOR_COMMAND_INVALID');
+            }
+            const result = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'accepted',
+                    completed_at = NULL,
+                    error_code = 'SYNC_COORDINATOR_RUNNER_RECREATED',
+                    error_message = 'The command was requeued after controlled runner recovery.',
+                    updated_at = ?
+                WHERE workspace_id = ?
+                  AND expected_coordinator_generation = ?
+                  AND command_type IN ('EnableSync', 'DisableSync', 'Sync', 'Retry', 'Repair')
+                  AND status = 'running'
+            `).run(this.now(), input.workspaceId, input.coordinatorGeneration);
+            return Number(result?.changes || 0);
+        })();
+    }
+    markCommandRunning(commandId) {
+        const at = this.now();
+        this.db.prepare(`
+            UPDATE local_sync_coordinator_commands
+            SET status = 'running', started_at = COALESCE(started_at, ?), updated_at = ?
+            WHERE command_id = ? AND status = 'accepted'
+        `).run(at, at, commandId);
+        return this.readCommand(commandId);
+    }
+    finishCommand(input) {
+        const at = this.now();
+        this.db.prepare(`
+            UPDATE local_sync_coordinator_commands
+            SET status = ?, completed_at = ?, result_json = ?, error_code = ?,
+                error_message = ?, updated_at = ?
+            WHERE command_id = ? AND status IN ('accepted', 'running')
+        `).run(input.status, at, input.result === undefined ? null : JSON.stringify(input.result), input.errorCode || null, input.errorMessage || null, at, input.commandId);
+        const command = this.readCommand(input.commandId);
+        this.pruneTerminalCommands();
+        return command;
+    }
+    recoverAfterRestart() {
+        const recovered = this.db.transaction(() => {
+            const state = this.readOrCreateState();
+            const at = this.now();
+            const interruptedTransfer = state.transitionState === 'transferring-ownership'
+                ? buildTerminalTransferRecord({
+                    state,
+                    completedAt: at,
+                    status: 'failed',
+                    errorCode: 'SYNC_COORDINATOR_RESTART_INTERRUPTED',
+                })
+                : null;
+            if (state.transitionState !== 'idle' || state.ownershipMode === 'server') {
+                if (state.activeWorkspaceId) {
+                    this.advanceRunnerStateGenerationIfPresent({
+                        workspaceId: state.activeWorkspaceId,
+                        expectedSourceGeneration: state.coordinatorGeneration,
+                        targetGeneration: state.coordinatorGeneration + 1,
+                        updatedAt: at,
+                    });
+                }
+                this.db.prepare(`
+                    UPDATE local_sync_coordinator_state
+                    SET coordinator_generation = coordinator_generation + 1,
+                        ownership_mode = CASE
+                            WHEN transition_state = 'transferring-ownership'
+                              OR ownership_mode = 'server' THEN 'stopped'
+                            ELSE 'browser-gateway'
+                        END,
+                        transition_state = 'idle',
+                        accepted_switch_command_id = NULL,
+                        target_workspace_id = NULL,
+                        requested_by_json = NULL,
+                        terminal_switch_result_json = CASE
+                            WHEN transition_state = 'switching-workspace' THEN ?
+                            ELSE terminal_switch_result_json
+                        END,
+                        terminal_transfer_result_json = CASE
+                            WHEN transition_state = 'transferring-ownership' THEN ?
+                            ELSE terminal_transfer_result_json
+                        END,
+                        accepted_transfer_command_id = NULL,
+                        transfer_target_mode = NULL,
+                        transfer_phase = NULL,
+                        transfer_version = NULL,
+                        updated_at = ?
+                    WHERE coordinator_id = ?
+                      AND (transition_state <> 'idle' OR ownership_mode = 'server')
+                `).run(JSON.stringify({
+                    status: 'failed',
+                    errorCode: 'SYNC_COORDINATOR_RESTART_INTERRUPTED',
+                }), interruptedTransfer ? JSON.stringify(interruptedTransfer) : null, at, LOCAL_SYNC_COORDINATOR_ID);
+            }
+            if (interruptedTransfer) {
+                this.db.prepare(`
+                    UPDATE local_sync_coordinator_commands
+                    SET result_json = ?
+                    WHERE command_id = ?
+                      AND status IN ('accepted', 'running')
+                `).run(JSON.stringify({ terminalTransfer: interruptedTransfer }), interruptedTransfer.commandId);
+            }
+            const neverStarted = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'failed', completed_at = ?,
+                    error_code = 'SYNC_COORDINATOR_RESTART_BEFORE_EXECUTION',
+                    error_message = 'The local sync server restarted before this accepted command began executing.',
+                    updated_at = ?
+                WHERE status = 'accepted'
+            `).run(at, at);
+            const interrupted = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'failed', completed_at = ?, error_code = 'SYNC_COORDINATOR_RESTART_INTERRUPTED',
+                    error_message = 'The local sync server restarted before this command reached a terminal result.',
+                    updated_at = ?
+                WHERE status = 'running'
+            `).run(at, at);
+            return {
+                state: this.readOrCreateState(),
+                interruptedCommandCount: Number(neverStarted?.changes || 0) + Number(interrupted?.changes || 0),
+            };
+        })();
+        this.pruneTerminalCommands();
+        return recovered;
+    }
+    pruneTerminalCommands() {
+        const nowMs = Date.parse(this.now());
+        if (!Number.isFinite(nowMs))
+            return 0;
+        const cutoff = new Date(nowMs - LOCAL_SYNC_COMMAND_RETENTION_MIN_AGE_MS).toISOString();
+        return this.db.transaction(() => {
+            const rows = this.db.prepare(`
+                SELECT *
+                FROM local_sync_coordinator_commands
+                WHERE status IN ('succeeded', 'failed', 'superseded')
+                  AND completed_at IS NOT NULL
+                ORDER BY completed_at DESC, command_id DESC
+            `).all().map(mapCommand);
+            if (rows.length <= LOCAL_SYNC_COMMAND_RETENTION_SOFT_LIMIT)
+                return 0;
+            const protectedIds = new Set();
+            for (const command of rows.slice(0, LOCAL_SYNC_COMMAND_RETENTION_SOFT_LIMIT)) {
+                protectedIds.add(command.commandId);
+            }
+            for (const command of rows) {
+                if (command.completedAt && command.completedAt >= cutoff) {
+                    protectedIds.add(command.commandId);
+                }
+            }
+            const state = this.readOrCreateState();
+            if (state.acceptedSwitchCommandId)
+                protectedIds.add(state.acceptedSwitchCommandId);
+            if (state.acceptedTransferCommandId)
+                protectedIds.add(state.acceptedTransferCommandId);
+            collectCommandReferences(state.terminalSwitchResult, protectedIds);
+            collectCommandReferences(state.terminalTransferResult, protectedIds);
+            const byId = new Map(rows.map((command) => [command.commandId, command]));
+            const queue = [...protectedIds];
+            const queued = new Set(queue);
+            for (let index = 0; index < queue.length; index += 1) {
+                const command = byId.get(queue[index]);
+                if (!command)
+                    continue;
+                collectCommandReferences(command.result, protectedIds);
+                for (const commandId of protectedIds) {
+                    if (queued.has(commandId))
+                        continue;
+                    queued.add(commandId);
+                    queue.push(commandId);
+                }
+            }
+            const candidates = rows
+                .filter((command) => (command.completedAt
+                && command.completedAt < cutoff
+                && !protectedIds.has(command.commandId)))
+                .reverse()
+                .slice(0, LOCAL_SYNC_COMMAND_RETENTION_DELETE_BATCH);
+            const remove = this.db.prepare(`
+                DELETE FROM local_sync_coordinator_commands
+                WHERE command_id = ?
+                  AND status IN ('succeeded', 'failed', 'superseded')
+            `);
+            let deleted = 0;
+            for (const command of candidates) {
+                const result = remove.run(command.commandId);
+                deleted += Number(result?.changes || 0);
+            }
+            return deleted;
+        })();
+    }
+    beginOwnershipTransfer(input) {
+        return this.db.transaction(() => {
+            const state = this.readOrCreateState();
+            if (state.coordinatorGeneration !== input.expectedGeneration) {
+                throw new LocalSyncCoordinatorError(`Coordinator generation ${input.expectedGeneration} is stale; current generation is ${state.coordinatorGeneration}.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            if (state.activeWorkspaceId !== input.workspaceId) {
+                throw new LocalSyncCoordinatorError(`Workspace ${input.workspaceId} is not the active local sync workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+            }
+            if (state.transitionState !== 'idle'
+                || !['browser-gateway', 'server'].includes(state.ownershipMode)
+                || state.ownershipMode === input.targetMode) {
+                throw new LocalSyncCoordinatorError('The requested ownership transfer does not match the current coordinator owner.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            const command = this.readCommand(input.commandId);
+            if (!command
+                || command.status !== 'accepted'
+                || command.type !== 'TransferOwnership'
+                || command.version !== input.version
+                || command.workspaceId !== input.workspaceId
+                || command.expectedCoordinatorGeneration !== input.expectedGeneration
+                || command.args?.targetMode !== input.targetMode
+                || command.requestedBy.userId !== input.requestedBy.userId
+                || command.requestedBy.tenantId !== input.requestedBy.tenantId) {
+                throw new LocalSyncCoordinatorError(`Ownership transfer command ${input.commandId} is not a matching running command.`, 'SYNC_COORDINATOR_COMMAND_INVALID');
+            }
+            const transitionMode = input.targetMode === 'server'
+                ? 'transitioning-to-server'
+                : 'transitioning-to-browser';
+            const at = this.now();
+            const result = this.db.prepare(`
+                UPDATE local_sync_coordinator_state
+                SET ownership_mode = ?,
+                    transition_state = 'transferring-ownership',
+                    accepted_transfer_command_id = ?,
+                    transfer_target_mode = ?,
+                    transfer_phase = 'preparing',
+                    transfer_version = ?,
+                    requested_by_json = ?,
+                    terminal_transfer_result_json = NULL,
+                    updated_at = ?
+                WHERE coordinator_id = ?
+                  AND coordinator_generation = ?
+                  AND active_workspace_id = ?
+                  AND transition_state = 'idle'
+                  AND ownership_mode = ?
+            `).run(transitionMode, input.commandId, input.targetMode, input.version, JSON.stringify(input.requestedBy), at, LOCAL_SYNC_COORDINATOR_ID, input.expectedGeneration, input.workspaceId, state.ownershipMode);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncCoordinatorError('The local sync coordinator changed before ownership transfer began.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            const commandResult = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'running', started_at = COALESCE(started_at, ?), updated_at = ?
+                WHERE command_id = ? AND status = 'accepted'
+            `).run(at, at, input.commandId);
+            if (Number(commandResult?.changes || 0) !== 1) {
+                throw new LocalSyncCoordinatorError(`Ownership transfer command ${input.commandId} changed before transition begin.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            return this.readOrCreateState();
+        })();
+    }
+    advanceOwnershipTransfer(input) {
+        const state = this.readOrCreateState();
+        const validNextPhases = {
+            preparing: ['draining'],
+            draining: [],
+            'generation-advanced': state.transferTargetMode === 'server'
+                ? ['starting-target']
+                : ['stopping-source'],
+            'starting-target': ['committing'],
+            'stopping-source': ['committing'],
+            committing: [],
+        };
+        if (state.acceptedTransferCommandId !== input.commandId
+            || state.transferPhase !== input.expectedPhase
+            || !validNextPhases[input.expectedPhase].includes(input.nextPhase)) {
+            throw new LocalSyncCoordinatorError('The requested ownership transfer phase advance is invalid or stale.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        const at = this.now();
+        const result = this.db.prepare(`
+            UPDATE local_sync_coordinator_state
+            SET transfer_phase = ?, updated_at = ?
+            WHERE coordinator_id = ?
+              AND accepted_transfer_command_id = ?
+              AND transition_state = 'transferring-ownership'
+              AND transfer_phase = ?
+              AND transfer_target_mode = ?
+        `).run(input.nextPhase, at, LOCAL_SYNC_COORDINATOR_ID, input.commandId, input.expectedPhase, state.transferTargetMode);
+        if (Number(result?.changes || 0) !== 1) {
+            throw new LocalSyncCoordinatorError('The ownership transfer phase changed before it could advance.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        return this.readOrCreateState();
+    }
+    advanceOwnershipTransferGeneration(input) {
+        return this.db.transaction(() => {
+            const state = this.readOrCreateState();
+            if (state.activeWorkspaceId === null
+                || state.acceptedTransferCommandId !== input.commandId
+                || state.transitionState !== 'transferring-ownership'
+                || state.transferPhase !== 'draining'
+                || state.coordinatorGeneration !== input.expectedSourceGeneration) {
+                throw new LocalSyncCoordinatorError('The ownership transfer generation changed before the post-drain fence could commit.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            const at = this.now();
+            this.advanceRunnerStateGenerationIfPresent({
+                workspaceId: state.activeWorkspaceId,
+                expectedSourceGeneration: input.expectedSourceGeneration,
+                targetGeneration: input.expectedSourceGeneration + 1,
+                updatedAt: at,
+            });
+            const result = this.db.prepare(`
+                UPDATE local_sync_coordinator_state
+                SET coordinator_generation = coordinator_generation + 1,
+                    transfer_phase = 'generation-advanced',
+                    updated_at = ?
+                WHERE coordinator_id = ?
+                  AND accepted_transfer_command_id = ?
+                  AND transition_state = 'transferring-ownership'
+                  AND transfer_phase = 'draining'
+                  AND coordinator_generation = ?
+            `).run(at, LOCAL_SYNC_COORDINATOR_ID, input.commandId, input.expectedSourceGeneration);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncCoordinatorError('The ownership transfer generation changed before the post-drain fence could commit.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            return this.readOrCreateState();
+        })();
+    }
+    advanceRunnerStateGenerationIfPresent(input) {
+        const rows = this.db.prepare(`
+            SELECT coordinator_generation AS coordinatorGeneration
+            FROM local_workspace_sync_runner_state
+            WHERE workspace_id = ?
+        `).all(input.workspaceId);
+        if (rows.length === 0)
+            return;
+        if (rows.some((row) => (Number(row.coordinatorGeneration) !== input.expectedSourceGeneration))) {
+            throw new LocalSyncCoordinatorError('The durable runner generation does not match the coordinator ownership fence.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+        const result = this.db.prepare(`
+            UPDATE local_workspace_sync_runner_state
+            SET coordinator_generation = ?,
+                checkpoint_revision = checkpoint_revision + 1,
+                updated_at = ?
+            WHERE workspace_id = ?
+              AND coordinator_generation = ?
+        `).run(input.targetGeneration, input.updatedAt, input.workspaceId, input.expectedSourceGeneration);
+        if (Number(result?.changes || 0) !== rows.length) {
+            throw new LocalSyncCoordinatorError('The durable runner generation changed before the coordinator fence could commit.', 'SYNC_COORDINATOR_STALE_GENERATION');
+        }
+    }
+    completeOwnershipTransfer(input, activateCommittedOwner) {
+        return this.db.transaction(() => {
+            const at = this.now();
+            const transitionState = this.readOrCreateState();
+            if (transitionState.acceptedTransferCommandId !== input.commandId
+                || transitionState.transferTargetMode !== input.targetMode
+                || transitionState.transferPhase !== 'committing') {
+                throw new LocalSyncCoordinatorError('The ownership transfer no longer owns the coordinator transition.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            const terminalTransfer = buildTerminalTransferRecord({
+                state: transitionState,
+                completedAt: at,
+                status: 'succeeded',
+            });
+            const stateResult = this.db.prepare(`
+                UPDATE local_sync_coordinator_state
+                SET ownership_mode = ?,
+                    desired_ownership_mode = ?,
+                    transition_state = 'idle',
+                    accepted_transfer_command_id = NULL,
+                    transfer_target_mode = NULL,
+                    transfer_phase = NULL,
+                    transfer_version = NULL,
+                    requested_by_json = NULL,
+                    terminal_transfer_result_json = ?,
+                    updated_at = ?
+                WHERE coordinator_id = ?
+                  AND accepted_transfer_command_id = ?
+                  AND transition_state = 'transferring-ownership'
+                  AND transfer_target_mode = ?
+                  AND transfer_phase = 'committing'
+            `).run(input.targetMode, input.targetMode, JSON.stringify(terminalTransfer), at, LOCAL_SYNC_COORDINATOR_ID, input.commandId, input.targetMode);
+            if (Number(stateResult?.changes || 0) !== 1) {
+                throw new LocalSyncCoordinatorError('The ownership transfer no longer owns the coordinator transition.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            const state = this.readOrCreateState();
+            const commandResult = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'succeeded', completed_at = ?, result_json = ?,
+                    error_code = NULL, error_message = NULL, updated_at = ?
+                WHERE command_id = ? AND status = 'running'
+            `).run(at, JSON.stringify({ state }), at, input.commandId);
+            if (Number(commandResult?.changes || 0) !== 1) {
+                throw new Error(`Ownership transfer command ${input.commandId} is not running.`);
+            }
+            const activationResult = activateCommittedOwner?.(state);
+            if (activationResult
+                && (typeof activationResult === 'object'
+                    || typeof activationResult === 'function')
+                && typeof activationResult.then === 'function') {
+                throw new LocalSyncCoordinatorError('Ownership activation must complete synchronously inside the coordinator transaction.', 'SYNC_COORDINATOR_COMMAND_INVALID');
+            }
+            return state;
+        })();
+    }
+    failOwnershipTransfer(input) {
+        return this.db.transaction(() => {
+            const at = this.now();
+            const transitionState = this.readOrCreateState();
+            if (transitionState.acceptedTransferCommandId !== input.commandId) {
+                throw new LocalSyncCoordinatorError('The ownership transfer no longer owns the coordinator transition.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            const terminalTransfer = buildTerminalTransferRecord({
+                state: transitionState,
+                completedAt: at,
+                status: 'failed',
+                errorCode: input.errorCode,
+            });
+            const stateResult = this.db.prepare(`
+                UPDATE local_sync_coordinator_state
+                SET ownership_mode = ?,
+                    desired_ownership_mode = CASE
+                        WHEN ? = 'browser-gateway' THEN 'browser-gateway'
+                        ELSE desired_ownership_mode
+                    END,
+                    transition_state = 'idle',
+                    accepted_transfer_command_id = NULL,
+                    transfer_target_mode = NULL,
+                    transfer_phase = NULL,
+                    transfer_version = NULL,
+                    requested_by_json = NULL,
+                    terminal_transfer_result_json = ?,
+                    updated_at = ?
+                WHERE coordinator_id = ?
+                  AND accepted_transfer_command_id = ?
+                  AND transition_state = 'transferring-ownership'
+            `).run(input.fallbackMode, input.fallbackMode, JSON.stringify(terminalTransfer), at, LOCAL_SYNC_COORDINATOR_ID, input.commandId);
+            if (Number(stateResult?.changes || 0) !== 1) {
+                throw new LocalSyncCoordinatorError('The ownership transfer no longer owns the coordinator transition.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            const commandResult = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'failed', completed_at = ?, result_json = ?, error_code = ?,
+                    error_message = ?, updated_at = ?
+                WHERE command_id = ? AND status IN ('accepted', 'running')
+            `).run(at, JSON.stringify({ terminalTransfer }), input.errorCode, input.errorMessage, at, input.commandId);
+            if (Number(commandResult?.changes || 0) !== 1) {
+                throw new Error(`Ownership transfer command ${input.commandId} is not active.`);
+            }
+            return this.readOrCreateState();
+        })();
+    }
+    beginWorkspaceSwitch(input) {
+        return this.db.transaction(() => {
+            const state = this.readOrCreateState();
+            if (state.coordinatorGeneration !== input.expectedGeneration) {
+                throw new LocalSyncCoordinatorError(`Coordinator generation ${input.expectedGeneration} is stale; current generation is ${state.coordinatorGeneration}.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            if (state.activeWorkspaceId !== input.expectedActiveWorkspaceId) {
+                throw new LocalSyncCoordinatorError(`Workspace ${input.expectedActiveWorkspaceId || '(none)'} is not the active local sync workspace.`, 'SYNC_COORDINATOR_INACTIVE_WORKSPACE');
+            }
+            if (state.transitionState !== 'idle') {
+                throw new LocalSyncCoordinatorError('The local sync coordinator is already switching workspaces.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            const updatedAt = this.now();
+            const result = this.db.prepare(`
+                UPDATE local_sync_coordinator_state
+                SET coordinator_generation = coordinator_generation + 1,
+                    ownership_mode = 'transitioning-workspace',
+                    transition_state = 'switching-workspace',
+                    accepted_switch_command_id = ?,
+                    target_workspace_id = ?,
+                    requested_by_json = ?,
+                    terminal_switch_result_json = NULL,
+                    updated_at = ?
+                WHERE coordinator_id = ?
+                  AND coordinator_generation = ?
+                  AND transition_state = 'idle'
+                  AND (
+                      active_workspace_id = ?
+                      OR (active_workspace_id IS NULL AND ? IS NULL)
+                  )
+            `).run(input.commandId, input.targetWorkspaceId, JSON.stringify(input.requestedBy), updatedAt, LOCAL_SYNC_COORDINATOR_ID, input.expectedGeneration, input.expectedActiveWorkspaceId, input.expectedActiveWorkspaceId);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncCoordinatorError('The local sync coordinator changed before the workspace switch was accepted.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            return this.readOrCreateState();
+        })();
+    }
+    completeWorkspaceSwitch(input) {
+        return this.db.transaction(() => {
+            const at = this.now();
+            const result = this.db.prepare(`
+                UPDATE local_sync_coordinator_state
+                SET active_workspace_id = ?,
+                    ownership_mode = 'browser-gateway',
+                    desired_ownership_mode = 'browser-gateway',
+                    transition_state = 'idle',
+                    accepted_switch_command_id = NULL,
+                    target_workspace_id = NULL,
+                    requested_by_json = NULL,
+                    terminal_switch_result_json = ?,
+                    updated_at = ?
+                WHERE coordinator_id = ?
+                  AND accepted_switch_command_id = ?
+                  AND transition_state = 'switching-workspace'
+            `).run(input.targetWorkspaceId, JSON.stringify(input.terminalResult ?? null), at, LOCAL_SYNC_COORDINATOR_ID, input.commandId);
+            if (Number(result?.changes || 0) !== 1) {
+                throw new LocalSyncCoordinatorError('The workspace switch no longer owns the coordinator transition.', 'SYNC_COORDINATOR_STALE_GENERATION');
+            }
+            input.activateTargetForCommit?.();
+            const state = this.readOrCreateState();
+            const commandResult = this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'succeeded', completed_at = ?, result_json = ?,
+                    error_code = NULL, error_message = NULL, updated_at = ?
+                WHERE command_id = ? AND status = 'running'
+            `).run(at, JSON.stringify({ state }), at, input.commandId);
+            if (Number(commandResult?.changes || 0) !== 1) {
+                throw new Error(`Workspace switch command ${input.commandId} is not running.`);
+            }
+            return state;
+        })();
+    }
+    failWorkspaceSwitch(input) {
+        return this.db.transaction(() => {
+            const at = this.now();
+            this.db.prepare(`
+                UPDATE local_sync_coordinator_state
+                SET ownership_mode = 'browser-gateway',
+                    desired_ownership_mode = 'browser-gateway',
+                    transition_state = 'idle',
+                    accepted_switch_command_id = NULL,
+                    target_workspace_id = NULL,
+                    requested_by_json = NULL,
+                    terminal_switch_result_json = ?,
+                    updated_at = ?
+                WHERE coordinator_id = ?
+                  AND accepted_switch_command_id = ?
+                  AND transition_state = 'switching-workspace'
+            `).run(JSON.stringify({
+                status: 'failed',
+                errorCode: input.errorCode,
+                errorMessage: input.errorMessage,
+            }), at, LOCAL_SYNC_COORDINATOR_ID, input.commandId);
+            this.db.prepare(`
+                UPDATE local_sync_coordinator_commands
+                SET status = 'failed', completed_at = ?, error_code = ?,
+                    error_message = ?, updated_at = ?
+                WHERE command_id = ? AND status IN ('accepted', 'running')
+            `).run(at, input.errorCode, input.errorMessage, at, input.commandId);
+            return this.readOrCreateState();
+        })();
+    }
+}