@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/sync/engine/workspaceSyncEngineServerRunnerOperations.js

@@ -0,0 +1,1147 @@
+import { createHash } from 'crypto';
+import { createLocalWorkspaceSyncPendingV2Push, decodeWorkspaceSyncPayload, fingerprintLocalWorkspaceSyncPreparedPlan, isLocalWorkspaceSyncPullFairnessDue, } from '../coordinator/localWorkspaceSyncRunnerState.js';
+import { isTransientWorkspaceSyncStatus, runWorkspacePullSyncService, runWorkspacePushSyncService, } from '../syncService.js';
+import { hydrateWorkspaceSyncV3AttachmentAsset } from '../v3/workspaceSyncV3AttachmentAssetHydration.js';
+import { runWorkspaceSyncV3CombinedProjectionCycle } from '../v3/workspaceSyncV3CombinedFeedOrchestrator.js';
+import { runWorkspaceSyncV3InitiativeProjectionCycle } from '../v3/workspaceSyncV3FeedOrchestrator.js';
+import { normalizeWorkspaceSyncV2ProjectionExclusions } from '../v3/workspaceSyncV2ProjectionExclusions.js';
+import { canonicalWorkspaceSyncJson } from '../v3/canonicalWorkspaceSyncJson.js';
+import { combinedAttachmentAssetHydrationId, createWorkspaceSyncV3TransferBindings, } from './workspaceSyncEngineTransfers.js';
+import { createWorkspaceSyncTransferEvidence, } from './workspaceSyncTransferEvidence.js';
+const NOOP_CLOUD_RESOLVER = (path) => path;
+const RETRY_BASE_DELAY_MS = 1_000;
+const RETRY_MAX_DELAY_MS = 5 * 60_000;
+const COMBINED_FEED_COVERED_OUTBOX_BLOCK = 'WORKSPACE_SYNC_V3_COVERED_LOCAL_OPERATIONS';
+const REPAIR_OWNERSHIP_FINGERPRINT_VERSION = 2;
+class WorkspaceSyncEngineServerRunnerOperationError extends Error {
+    code;
+    retryAfterMs;
+    constructor(message, code, retryAfterMs) {
+        super(message);
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'WorkspaceSyncEngineServerRunnerOperationError';
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function repairOwnershipFingerprint(ownership) {
+    return createHash('sha256').update(canonicalWorkspaceSyncJson({
+        initiativeFeedActivationEnabled: ownership.initiativeFeedActivationEnabled ?? null,
+        initiativeProjection: ownership.initiativeProjection
+            ? { owner: ownership.initiativeProjection.owner }
+            : null,
+        combinedFeedActivationEnabled: ownership.combinedFeedActivationEnabled ?? null,
+        combinedProjection: ownership.combinedProjection
+            ? {
+                owner: ownership.combinedProjection.owner,
+                coverageProfileId: ownership.combinedProjection.coverageProfileId,
+                coverageVersion: ownership.combinedProjection.coverageVersion,
+                coverageDigest: ownership.combinedProjection.coverageDigest,
+            }
+            : null,
+        combinedFeedCoverage: ownership.combinedFeedCoverage ?? null,
+        combinedFeedExcludedProjections: ownership.combinedFeedExcludedProjections ?? null,
+    })).digest('hex');
+}
+function isFencedRepairContinuation(value) {
+    return value !== null && 'continuationVersion' in value;
+}
+function hasCompletedV3RepairStage(continuation) {
+    return continuation.kind === 'v2-reconcile'
+        || continuation.kind === 'final-push'
+        || continuation.kind === 'settlement';
+}
+function retryDelayMs(attempt, requested) {
+    if (Number.isFinite(requested) && Number(requested) >= 0) {
+        return Math.min(RETRY_MAX_DELAY_MS, Math.floor(Number(requested)));
+    }
+    return Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * (2 ** Math.min(18, Math.max(0, attempt - 1))));
+}
+function errorMessage(error, fallback) {
+    const detail = String(error?.message || '').trim();
+    return detail || fallback;
+}
+function isAuthFailure(result) {
+    return result.status === 401 || result.kind === 'apply_auth';
+}
+function pullFailureMessage(result) {
+    return String(result.error || '').trim()
+        || `Workspace sync pull failed (${result.status || 0}).`;
+}
+function pushFailureMessage(result) {
+    return String(result.error || '').trim()
+        || `Workspace sync push failed (${result.status || 0}).`;
+}
+/**
+ * Browser-neutral operation implementation for the dark server-owned runner.
+ *
+ * The factory deliberately depends only on engine ports. It does not construct
+ * the browser transfer coordinator and it does not activate server ownership.
+ */
+export function createWorkspaceSyncEngineServerRunnerOperations(options) {
+    const workspaceId = String(options.workspaceId || '').trim();
+    if (!workspaceId)
+        throw new TypeError('The server sync runner workspace is required.');
+    const resolveV3Ownership = options.resolveV3Ownership
+        || (() => ({
+            initiativeFeedActivationEnabled: options.initiativeFeedActivationEnabled,
+            combinedFeedActivationEnabled: options.combinedFeedActivationEnabled,
+            combinedFeedCoverage: options.combinedFeedCoverage,
+        }));
+    const now = options.now;
+    const commitTransferEvidence = (evidence, errorMessage) => options.recordTransferEvidence
+        ? () => options.recordTransferEvidence(evidence, errorMessage)
+        : undefined;
+    const execute = async (input, mode) => {
+        let checkpoint = structuredClone(input.checkpoint);
+        const v2ContentPushRetry = mode === 'retry'
+            && input.checkpoint.retry?.kind === 'v2-content-push';
+        if ((mode === 'sync' || mode === 'retry')
+            && !v2ContentPushRetry
+            && (checkpoint.repairContinuation !== null
+                || Number(options.coordinatorRecovery?.inspectRepairableObligations().total || 0) > 0)) {
+            mode = 'repair';
+        }
+        let v3Ownership = null;
+        let activeRetryKind = mode === 'repair'
+            ? 'repair'
+            : 'pull';
+        const transferMode = mode === 'repair' || mode === 'retry' ? mode : 'sync';
+        let activeFailureEvidence = null;
+        let failureEvidenceCommitted = false;
+        let transferBoundaryCheckpointTransform = ({ checkpoint }) => checkpoint;
+        const persist = (next, options) => {
+            const persisted = input.persistCheckpoint(next, options);
+            checkpoint = structuredClone(persisted.checkpoint);
+            return checkpoint;
+        };
+        const setRetry = (kind, message, requestedDelayMs, beforeCommit) => {
+            const previousAttempt = checkpoint.retry?.kind === kind
+                ? checkpoint.retry.attempt
+                : 0;
+            const attempt = Math.min(Number.MAX_SAFE_INTEGER, previousAttempt + 1);
+            persist({
+                ...checkpoint,
+                controlState: 'retry-wait',
+                retry: {
+                    kind,
+                    attempt,
+                    retryAt: new Date(Date.parse(input.now) + retryDelayMs(attempt, requestedDelayMs)).toISOString(),
+                },
+                lastError: message,
+            }, { beforeCommit });
+        };
+        const fail = (kind, message, code, requestedDelayMs) => {
+            const beforeCommit = activeFailureEvidence?.(message, code);
+            setRetry(kind, message, requestedDelayMs, beforeCommit);
+            failureEvidenceCommitted = Boolean(beforeCommit);
+            throw new WorkspaceSyncEngineServerRunnerOperationError(message, code, requestedDelayMs);
+        };
+        const localServices = options.createLocalServices({
+            checkpointPort: {
+                readCheckpoint: () => structuredClone(checkpoint),
+                persistCheckpoint: persist,
+                transformCheckpointAtTransferBoundary: (boundary) => (transferBoundaryCheckpointTransform(boundary)),
+            },
+        });
+        const prepareAndDrainRecoveryReplay = async (preparedRecovery) => {
+            let recovery = preparedRecovery
+                ?? await localServices.prepareOutboxRecovery(workspaceId);
+            if (recovery.kind === 'recovery' && recovery.state === 'replay_queued') {
+                const drainResult = await options.drainV3Outbox?.({
+                    beforeTransport: () => undefined,
+                });
+                if (drainResult === 'v2-content-push-required') {
+                    fail('v2-content-push', 'A referenced attachment must be published before durable repair can continue.', 'SYNC_RUNNER_V2_CONTENT_PUSH_REQUIRED');
+                }
+                recovery = await localServices.prepareOutboxRecovery(workspaceId);
+            }
+            return recovery;
+        };
+        const ensureReady = options.ensureCloudWorkspaceReadyForSync
+            || (async () => {
+                const result = await options.remoteServices.handshakeWorkspace(workspaceId);
+                if (result.ok)
+                    return { success: true };
+                const data = isRecord(result.data) ? result.data : {};
+                return {
+                    success: false,
+                    statusCode: result.status,
+                    retryAfterMs: result.retryAfterMs,
+                    transient: isTransientWorkspaceSyncStatus(result.status),
+                    error: String(data.error || 'Workspace sync handshake failed.'),
+                };
+            });
+        const runV3Pull = async (input) => {
+            const v3RetryKind = mode === 'repair' ? 'repair' : 'v3-dispatch';
+            const bindings = createWorkspaceSyncV3TransferBindings({
+                workspaceId,
+                remoteServices: options.remoteServices,
+                localServices,
+            });
+            const onChangesApplied = (changeCount) => {
+                const boundedChangeCount = Math.max(0, Math.floor(Number(changeCount) || 0));
+                input.onChangesApplied?.(boundedChangeCount);
+            };
+            try {
+                if (!v3Ownership) {
+                    throw new Error('The server sync runner V3 ownership snapshot was not resolved.');
+                }
+                let excludeInitiatives = false;
+                let excludedProjections = [];
+                if (v3Ownership.combinedFeedActivationEnabled === true) {
+                    const initiativeRollback = await runWorkspaceSyncV3InitiativeProjectionCycle({
+                        activationEnabled: false,
+                        resolveCloudAuthUrl: NOOP_CLOUD_RESOLVER,
+                        workspaceId,
+                        onChangesApplied,
+                        dependencies: bindings.initiative,
+                    });
+                    if (initiativeRollback.kind === 'auth-failure') {
+                        fail(v3RetryKind, 'Workspace sync authentication is required.', 'SYNC_RUNNER_AUTH_REQUIRED');
+                    }
+                    if (initiativeRollback.kind === 'transient-failure') {
+                        fail(v3RetryKind, initiativeRollback.error, 'SYNC_RUNNER_V3_INITIATIVE_FAILED', initiativeRollback.retryAfterMs);
+                    }
+                    const runCombinedCycle = () => runWorkspaceSyncV3CombinedProjectionCycle({
+                        activationEnabled: true,
+                        coverage: v3Ownership.combinedFeedCoverage,
+                        resolveCloudAuthUrl: NOOP_CLOUD_RESOLVER,
+                        workspaceId,
+                        forceAuthoritativeRepair: input.forceAuthoritativeRepair,
+                        ...(input.recoveryBatchId
+                            ? { recoveryBatchId: input.recoveryBatchId }
+                            : {}),
+                        onChangesApplied,
+                        dependencies: bindings.combined,
+                    });
+                    let combined = await runCombinedCycle();
+                    if (combined.kind === 'transient-failure'
+                        && combined.causeCode === COMBINED_FEED_COVERED_OUTBOX_BLOCK
+                        && options.drainV3Outbox) {
+                        // A fairness pull is allowed to bypass ordinary pushing,
+                        // but covered local operations make that pull unsafe to
+                        // apply. Treat only this exact apply guard as a bounded
+                        // recovery transition, settle the durable rows, abandon
+                        // the failed receipt, and retry from the unchanged cursor.
+                        await bindings.abandonPendingReceipts();
+                        const drainResult = await options.drainV3Outbox({
+                            beforeTransport: () => {
+                                if (!checkpoint.remoteHintObservedAt)
+                                    return;
+                                persist({
+                                    ...checkpoint,
+                                    consecutivePushesWhilePullDue: Math.min(Number.MAX_SAFE_INTEGER, checkpoint.consecutivePushesWhilePullDue + 1),
+                                });
+                            },
+                        });
+                        if (drainResult === 'v2-content-push-required') {
+                            fail('v2-content-push', 'A referenced attachment must be published before covered workspace changes can be received.', 'SYNC_RUNNER_V2_CONTENT_PUSH_REQUIRED');
+                        }
+                        if (drainResult === 'budget-exhausted') {
+                            fail(v3RetryKind, 'Durable local operations are still draining before cloud changes can be received.', 'SYNC_RUNNER_V3_OUTBOX_DRAIN_BUDGET_EXHAUSTED');
+                        }
+                        combined = await runCombinedCycle();
+                    }
+                    if (combined.kind === 'auth-failure') {
+                        fail(v3RetryKind, 'Workspace sync authentication is required.', 'SYNC_RUNNER_AUTH_REQUIRED');
+                    }
+                    if (combined.kind === 'transient-failure') {
+                        const assetId = combinedAttachmentAssetHydrationId(combined);
+                        if (assetId) {
+                            await bindings.abandonPendingReceipts();
+                            const hydration = await hydrateWorkspaceSyncV3AttachmentAsset({
+                                workspaceId,
+                                assetId,
+                                remoteServices: options.remoteServices,
+                                localServices,
+                            }).catch((error) => ({
+                                success: false,
+                                error: errorMessage(error, 'Workspace attachment hydration failed.'),
+                            }));
+                            const hydrationMessage = hydration.success
+                                ? `${combined.error} The missing attachment was hydrated; retrying the projection cycle.`
+                                : `${combined.error} Attachment hydration failed: ${hydration.error}`;
+                            fail(v3RetryKind, hydrationMessage, hydration.success
+                                ? 'SYNC_RUNNER_V3_ATTACHMENT_HYDRATED_RETRY'
+                                : 'SYNC_RUNNER_V3_ATTACHMENT_HYDRATION_FAILED', combined.retryAfterMs);
+                        }
+                        fail(v3RetryKind, combined.error, 'SYNC_RUNNER_V3_COMBINED_FAILED', combined.retryAfterMs);
+                    }
+                    if (options.attachmentApply) {
+                        const obligations = await options.attachmentApply.processDue({
+                            limit: 5,
+                            hydrateAsset: async (assetId) => hydrateWorkspaceSyncV3AttachmentAsset({
+                                workspaceId,
+                                assetId,
+                                remoteServices: options.remoteServices,
+                                localServices,
+                            }).catch((error) => ({
+                                success: false,
+                                error: errorMessage(error, 'Workspace attachment hydration failed.'),
+                            })),
+                        });
+                    }
+                    excludedProjections = combined.excludedProjections;
+                }
+                else {
+                    if (v3Ownership.combinedFeedActivationEnabled !== undefined) {
+                        const combined = await runWorkspaceSyncV3CombinedProjectionCycle({
+                            activationEnabled: false,
+                            coverage: v3Ownership.combinedFeedCoverage,
+                            resolveCloudAuthUrl: NOOP_CLOUD_RESOLVER,
+                            workspaceId,
+                            onChangesApplied,
+                            dependencies: bindings.combined,
+                        });
+                        if (combined.kind === 'auth-failure') {
+                            fail(v3RetryKind, 'Workspace sync authentication is required.', 'SYNC_RUNNER_AUTH_REQUIRED');
+                        }
+                        if (combined.kind === 'transient-failure') {
+                            fail(v3RetryKind, combined.error, 'SYNC_RUNNER_V3_COMBINED_FAILED', combined.retryAfterMs);
+                        }
+                    }
+                    if (v3Ownership.initiativeFeedActivationEnabled !== undefined) {
+                        const initiative = await runWorkspaceSyncV3InitiativeProjectionCycle({
+                            activationEnabled: v3Ownership.initiativeFeedActivationEnabled,
+                            resolveCloudAuthUrl: NOOP_CLOUD_RESOLVER,
+                            workspaceId,
+                            onChangesApplied,
+                            dependencies: bindings.initiative,
+                        });
+                        if (initiative.kind === 'auth-failure') {
+                            fail(v3RetryKind, 'Workspace sync authentication is required.', 'SYNC_RUNNER_AUTH_REQUIRED');
+                        }
+                        if (initiative.kind === 'transient-failure') {
+                            fail(v3RetryKind, initiative.error, 'SYNC_RUNNER_V3_INITIATIVE_FAILED', initiative.retryAfterMs);
+                        }
+                        excludeInitiatives = initiative.excludeInitiativesFromV2;
+                    }
+                }
+                return { excludeInitiatives, excludedProjections };
+            }
+            finally {
+                await bindings.abandonPendingReceipts();
+            }
+        };
+        const executePull = async (repairMode, recovery, onV3ChangesApplied, onV2Result, beforeTerminalPersist, skipOutboxDrain = false) => {
+            activeRetryKind = repairMode ? 'repair' : 'pull';
+            persist({
+                ...checkpoint,
+                controlState: repairMode ? 'repairing' : 'pulling',
+            });
+            let v3;
+            if (repairMode) {
+                const continuation = checkpoint.repairContinuation;
+                if (!isFencedRepairContinuation(continuation)) {
+                    throw new WorkspaceSyncEngineServerRunnerOperationError('Authoritative repair is missing its durable stage fence.', 'SYNC_RUNNER_REPAIR_CONTINUATION_INVALID');
+                }
+                if (continuation.kind === 'v3-combined') {
+                    v3 = await runV3Pull({
+                        forceAuthoritativeRepair: continuation.forceAuthoritativeRepair,
+                        ...(continuation.recoveryBatchId
+                            ? { recoveryBatchId: continuation.recoveryBatchId }
+                            : {}),
+                        onChangesApplied: onV3ChangesApplied,
+                        skipOutboxDrain,
+                    });
+                    persist({
+                        ...checkpoint,
+                        repairContinuation: {
+                            ...continuation,
+                            kind: 'v2-reconcile',
+                            cursor: checkpoint.pullCursor,
+                            excludeInitiatives: v3.excludeInitiatives,
+                            excludedProjections: [...v3.excludedProjections],
+                        },
+                    });
+                }
+                else if (continuation.kind === 'v2-reconcile') {
+                    v3 = {
+                        excludeInitiatives: continuation.excludeInitiatives,
+                        excludedProjections: normalizeWorkspaceSyncV2ProjectionExclusions(continuation.excludedProjections),
+                    };
+                }
+                else {
+                    throw new WorkspaceSyncEngineServerRunnerOperationError(`Authoritative pull cannot resume from ${continuation.kind}.`, 'SYNC_RUNNER_REPAIR_CONTINUATION_INVALID');
+                }
+            }
+            else {
+                v3 = await runV3Pull({
+                    forceAuthoritativeRepair: recovery?.forceAuthoritativeRepair === true,
+                    ...(recovery?.recoveryBatchId
+                        ? { recoveryBatchId: recovery.recoveryBatchId }
+                        : {}),
+                    onChangesApplied: onV3ChangesApplied,
+                    skipOutboxDrain,
+                });
+            }
+            if (repairMode && checkpoint.repairContinuation?.kind !== 'v2-reconcile') {
+                throw new WorkspaceSyncEngineServerRunnerOperationError('Authoritative repair did not persist its V2 stage boundary.', 'SYNC_RUNNER_REPAIR_CONTINUATION_INVALID');
+            }
+            if (repairMode) {
+                persist({
+                    ...checkpoint,
+                    pullCursor: checkpoint.repairContinuation?.cursor ?? checkpoint.pullCursor,
+                });
+            }
+            const result = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl: NOOP_CLOUD_RESOLVER,
+                workspaceId,
+                cursor: checkpoint.pullCursor,
+                bootstrap: checkpoint.syncPhase === 'attach-cloud',
+                ensureCloudWorkspaceReadyForSync: ensureReady,
+                maxPages: repairMode ? 200 : 20,
+                repairMode,
+                contentMode: repairMode ? 'manifest' : 'full',
+                excludeInitiatives: v3.excludeInitiatives,
+                excludedProjections: v3.excludedProjections,
+                remoteServices: options.remoteServices,
+                localServices,
+            });
+            onV2Result?.(result);
+            if (!result.success) {
+                const message = pullFailureMessage(result);
+                if (!repairMode && result.errorCode === 'INVALID_SYNC_CURSOR') {
+                    persist({
+                        ...checkpoint,
+                        pullCursor: null,
+                        repairContinuation: null,
+                    });
+                }
+                if (isAuthFailure(result)) {
+                    fail(repairMode ? 'repair' : 'pull', message, 'SYNC_RUNNER_AUTH_REQUIRED');
+                }
+                fail(repairMode ? 'repair' : 'pull', message, 'SYNC_RUNNER_PULL_FAILED', result.retryAfterMs);
+            }
+            if (repairMode && result.hasMore) {
+                fail('repair', 'Workspace sync repair did not reach the complete cloud snapshot.', 'SYNC_RUNNER_REPAIR_INCOMPLETE');
+            }
+            const syncedAt = result.syncedAt || input.now;
+            persist({
+                ...checkpoint,
+                controlState: repairMode ? 'repairing' : 'pulling',
+                pullCursor: result.cursor,
+                remoteHintObservedAt: null,
+                consecutivePushesWhilePullDue: 0,
+                retry: null,
+                repairContinuation: repairMode && isFencedRepairContinuation(checkpoint.repairContinuation)
+                    ? {
+                        ...checkpoint.repairContinuation,
+                        kind: 'final-push',
+                        cursor: result.cursor,
+                    }
+                    : checkpoint.repairContinuation,
+                lastPullAt: syncedAt,
+                lastSyncedAt: syncedAt,
+                lastError: null,
+            }, {
+                beforeCommit: beforeTerminalPersist
+                    ? () => beforeTerminalPersist(result)
+                    : undefined,
+            });
+            return result;
+        };
+        const pull = async (repairMode, recovery, skipOutboxDrain = false) => {
+            const startedAtMs = now().getTime();
+            let v3AppliedChanges = 0;
+            let v3Pages = 0;
+            let result = null;
+            const evidence = (outcome, errorCode) => {
+                const processedChanges = v3AppliedChanges + (result?.appliedChanges || 0);
+                const processedPages = v3Pages + (result?.pages || 0);
+                const isComplete = outcome === 'success' && result?.hasMore !== true;
+                const contentReconciliation = isRecord(result?.serverDiagnostics?.contentReconciliation)
+                    ? result.serverDiagnostics.contentReconciliation
+                    : null;
+                const contentBytes = contentReconciliation
+                    ? Number(contentReconciliation.contentBytesTransferred)
+                    : Number.NaN;
+                return createWorkspaceSyncTransferEvidence({
+                    direction: 'incoming',
+                    operation: 'pull',
+                    mode: transferMode,
+                    outcome,
+                    processedChanges,
+                    knownTotalChanges: isComplete ? processedChanges : null,
+                    remainingChanges: isComplete ? 0 : null,
+                    processedPages,
+                    knownTotalPages: isComplete ? processedPages : null,
+                    remainingPages: isComplete ? 0 : null,
+                    transferredBytes: Number.isFinite(contentBytes) ? contentBytes : null,
+                    transferredBytesScope: Number.isFinite(contentBytes)
+                        ? 'content-bodies'
+                        : null,
+                    durationMs: now().getTime() - startedAtMs,
+                    commandId: input.command?.commandId,
+                    errorCode,
+                });
+            };
+            activeFailureEvidence = (message, code) => commitTransferEvidence(evidence('error', code), message);
+            try {
+                result = await executePull(repairMode, recovery, (changeCount) => {
+                    v3AppliedChanges += changeCount;
+                    v3Pages += 1;
+                }, (v2Result) => {
+                    result = v2Result;
+                }, () => {
+                    options.recordTransferEvidence?.(evidence('success'));
+                }, skipOutboxDrain);
+                return result;
+            }
+            catch (error) {
+                if (!failureEvidenceCommitted && options.recordTransferEvidence) {
+                    persist(checkpoint, {
+                        beforeCommit: commitTransferEvidence(evidence('error', String(error?.code || '')), errorMessage(error, 'Workspace sync pull failed.')),
+                    });
+                    failureEvidenceCommitted = true;
+                }
+                throw error;
+            }
+            finally {
+                activeFailureEvidence = null;
+            }
+        };
+        const executePush = async (attemptOptions, onResult, beforeTerminalPersist, transformTerminalCheckpoint) => {
+            const pushRetryKind = mode === 'v2-content-push-only'
+                || (mode === 'retry'
+                    && checkpoint.retry?.kind === 'v2-content-push')
+                ? 'v2-content-push'
+                : attemptOptions.repairMode
+                    ? 'repair'
+                    : 'push';
+            activeRetryKind = pushRetryKind;
+            persist({ ...checkpoint, controlState: 'pushing' });
+            let payload;
+            let signature;
+            if (checkpoint.pendingV2Push) {
+                payload = decodeWorkspaceSyncPayload(checkpoint.pendingV2Push.frozenPayload);
+                signature = checkpoint.pendingV2Push.signature;
+                attemptOptions = {
+                    forceAllAiProfiles: checkpoint.pendingV2Push.forceAllAiProfiles,
+                    repairMode: checkpoint.pendingV2Push.repairMode,
+                };
+            }
+            else {
+                const forcedContentPaths = pushRetryKind === 'v2-content-push'
+                    ? options.resolveV2ContentPrerequisitePaths?.({ workspaceId })
+                    : undefined;
+                const candidate = await options.pushCandidateProvider.buildPushCandidate({
+                    workspaceId,
+                    pushBaseline: checkpoint.pushBaseline,
+                    forceAllAiProfiles: attemptOptions.forceAllAiProfiles,
+                    repairMode: attemptOptions.repairMode,
+                    forceDocumentPaths: forcedContentPaths?.documentPaths,
+                    forceAssetPaths: forcedContentPaths?.assetPaths,
+                });
+                signature = String(candidate.signature || '').trim();
+                if (!signature) {
+                    throw new WorkspaceSyncEngineServerRunnerOperationError('The server sync snapshot did not produce a push signature.', 'SYNC_RUNNER_PUSH_CANDIDATE_INVALID');
+                }
+                payload = candidate.payload;
+                const pendingV2Push = createLocalWorkspaceSyncPendingV2Push({
+                    signature,
+                    payload,
+                    forceAllAiProfiles: attemptOptions.forceAllAiProfiles,
+                    repairMode: attemptOptions.repairMode,
+                });
+                // The frozen identity must be durable before any cloud request.
+                persist({ ...checkpoint, pendingV2Push });
+            }
+            if (checkpoint.remoteHintObservedAt) {
+                persist({
+                    ...checkpoint,
+                    consecutivePushesWhilePullDue: Math.min(Number.MAX_SAFE_INTEGER, checkpoint.consecutivePushesWhilePullDue + 1),
+                });
+            }
+            const result = await runWorkspacePushSyncService({
+                resolveCloudAuthUrl: NOOP_CLOUD_RESOLVER,
+                workspaceId,
+                payload,
+                ensureCloudWorkspaceReadyForSync: ensureReady,
+                repairMode: attemptOptions.repairMode,
+                remoteServices: options.remoteServices,
+                localServices,
+                preparedPlan: checkpoint.pendingV2Push?.preparedPlan,
+                acknowledgedNonApplyingBatchOperationIdentities: checkpoint.pendingV2Push
+                    ?.acknowledgedNonApplyingBatchOperationIdentities,
+                onPreparedPlan: ({ plan, acknowledgedOperationIdentities, }) => {
+                    const pendingV2Push = checkpoint.pendingV2Push;
+                    if (!pendingV2Push) {
+                        throw new WorkspaceSyncEngineServerRunnerOperationError('The frozen V2 push disappeared while recording its prepared plan.', 'SYNC_RUNNER_PUSH_CHECKPOINT_INVALID');
+                    }
+                    persist({
+                        ...checkpoint,
+                        pendingV2Push: {
+                            ...pendingV2Push,
+                            preparedPlan: plan,
+                            preparedPlanFingerprint: fingerprintLocalWorkspaceSyncPreparedPlan(plan),
+                            acknowledgedNonApplyingBatchOperationIdentities: [
+                                ...acknowledgedOperationIdentities,
+                            ],
+                        },
+                    });
+                },
+                onNonApplyingBatchAcknowledged: ({ acknowledgedOperationIdentities }) => {
+                    const pendingV2Push = checkpoint.pendingV2Push;
+                    if (!pendingV2Push) {
+                        throw new WorkspaceSyncEngineServerRunnerOperationError('The frozen V2 push disappeared while recording batch progress.', 'SYNC_RUNNER_PUSH_CHECKPOINT_INVALID');
+                    }
+                    persist({
+                        ...checkpoint,
+                        pendingV2Push: {
+                            ...pendingV2Push,
+                            acknowledgedNonApplyingBatchOperationIdentities: [
+                                ...acknowledgedOperationIdentities,
+                            ],
+                        },
+                    });
+                },
+            });
+            onResult?.(result);
+            if (!result.success) {
+                if (result.batchProgress && checkpoint.pendingV2Push) {
+                    persist({
+                        ...checkpoint,
+                        pendingV2Push: {
+                            ...checkpoint.pendingV2Push,
+                            lastBatchProgress: structuredClone(result.batchProgress),
+                        },
+                    });
+                }
+                const message = pushFailureMessage(result);
+                if (isAuthFailure(result)) {
+                    fail(pushRetryKind, message, 'SYNC_RUNNER_AUTH_REQUIRED');
+                }
+                fail(pushRetryKind, message, 'SYNC_RUNNER_PUSH_FAILED', result.retryAfterMs);
+            }
+            for (const entry of result.appliedTaskUpserts || []) {
+                const taskId = String(entry.task.id || '').trim();
+                const watermark = String(entry.task.updatedAt || entry.task.createdAt || '').trim();
+                if (!taskId || !watermark)
+                    continue;
+                result.currentTaskWatermarks?.set(taskId, watermark);
+                result.pushedWatermarks.set(taskId, watermark);
+            }
+            const pushBaseline = options.pushCandidateProvider.buildPushBaseline({
+                workspaceId,
+                previousBaseline: checkpoint.pushBaseline,
+                payload,
+                result,
+            });
+            const syncedAt = result.syncedAt || input.now;
+            const appliedTaskUpserts = result.appliedTaskUpserts || [];
+            const pushTransferReceipts = result.pushTransferReceipts || [];
+            if (appliedTaskUpserts.length > 0) {
+                // Persist the retry obligation before entering the atomic local
+                // apply. If that transaction rolls back after its checkpoint
+                // callback, the runner resumes from this durable revision.
+                setRetry(pushRetryKind, 'Authoritative V2 push echo local commit is pending.');
+            }
+            const baseNextCheckpoint = {
+                ...checkpoint,
+                controlState: 'pushing',
+                pendingV2Push: null,
+                pushBaseline,
+                retry: null,
+                lastPushAt: syncedAt,
+                lastSyncedAt: syncedAt,
+                lastError: null,
+            };
+            const nextCheckpoint = transformTerminalCheckpoint
+                ? transformTerminalCheckpoint(baseNextCheckpoint, result, signature)
+                : baseNextCheckpoint;
+            if (appliedTaskUpserts.length > 0) {
+                const abandonPushReceipts = async (errorCode) => {
+                    if (pushTransferReceipts.length === 0)
+                        return;
+                    try {
+                        await options.remoteServices.abandonTransferReceipts({
+                            workspaceId,
+                            receipts: pushTransferReceipts,
+                            errorCode,
+                        });
+                    }
+                    catch {
+                        // The durable retry checkpoint remains authoritative.
+                        // The next exact replay will recover the retained or
+                        // ambiguous permit through the gateway.
+                    }
+                };
+                const completionGroup = result.pushBoundary
+                    ? options.remoteServices.buildV2PushApplyCompletionGroup({
+                        workspaceId,
+                        pushBoundary: result.pushBoundary,
+                        receipts: pushTransferReceipts,
+                    })
+                    : undefined;
+                if (!completionGroup) {
+                    await abandonPushReceipts('WORKSPACE_SYNC_V2_PUSH_APPLY_COMPLETION_INVALID');
+                    throw new WorkspaceSyncEngineServerRunnerOperationError('Accepted V2 push echoes are missing an atomic local apply completion group.', 'SYNC_RUNNER_PUSH_APPLY_COMPLETION_INVALID');
+                }
+                const commitState = {};
+                let applyResult;
+                try {
+                    applyResult = await localServices.applyV2Batch(workspaceId, appliedTaskUpserts.map((entry) => ({
+                        op: 'upsert',
+                        archived: entry.archived === true,
+                        task: entry.task,
+                        ...(entry.durableRevision
+                            ? { durableRevision: entry.durableRevision }
+                            : {}),
+                    })), {
+                        ...(completionGroup ? { completionGroup } : {}),
+                        commitServerCheckpoint: () => {
+                            const persisted = input.persistCheckpoint(nextCheckpoint, {
+                                beforeCommit: beforeTerminalPersist
+                                    ? () => beforeTerminalPersist(result)
+                                    : undefined,
+                            });
+                            commitState.checkpoint =
+                                structuredClone(persisted.checkpoint);
+                            return commitState.checkpoint;
+                        },
+                    });
+                }
+                catch (error) {
+                    await abandonPushReceipts('WORKSPACE_SYNC_V2_PUSH_AUTHORITATIVE_APPLY_FAILED');
+                    throw new WorkspaceSyncEngineServerRunnerOperationError(errorMessage(error, 'Authoritative V2 push echo apply failed.'), 'SYNC_RUNNER_PUSH_AUTHORITATIVE_APPLY_FAILED');
+                }
+                if (!applyResult.ok || !commitState.checkpoint) {
+                    await abandonPushReceipts('WORKSPACE_SYNC_V2_PUSH_AUTHORITATIVE_APPLY_FAILED');
+                    throw new WorkspaceSyncEngineServerRunnerOperationError(`Authoritative V2 push echo apply failed (${applyResult.status || 0}).`, 'SYNC_RUNNER_PUSH_AUTHORITATIVE_APPLY_FAILED');
+                }
+                const committedCheckpoint = commitState.checkpoint;
+                if (!committedCheckpoint) {
+                    throw new WorkspaceSyncEngineServerRunnerOperationError('The authoritative V2 push echo apply did not commit its runner checkpoint.', 'SYNC_RUNNER_PUSH_CHECKPOINT_NOT_COMMITTED');
+                }
+                checkpoint = structuredClone(committedCheckpoint);
+            }
+            else {
+                persist(nextCheckpoint, {
+                    beforeCommit: beforeTerminalPersist
+                        ? () => beforeTerminalPersist(result)
+                        : undefined,
+                });
+            }
+            return result;
+        };
+        const push = async (attemptOptions, transformTerminalCheckpoint) => {
+            const startedAtMs = now().getTime();
+            let result = null;
+            const evidence = (outcome, errorCode) => createWorkspaceSyncTransferEvidence({
+                direction: 'outgoing',
+                operation: 'push',
+                mode: transferMode,
+                outcome,
+                processedChanges: result?.batchProgress?.completedChanges
+                    ?? (outcome === 'success' ? result?.changeCount || 0 : 0),
+                knownTotalChanges: result?.batchProgress
+                    ? result.changeCount
+                    : outcome === 'success'
+                        ? result?.changeCount || 0
+                        : null,
+                remainingChanges: result?.batchProgress
+                    ? Math.max(0, result.changeCount - result.batchProgress.completedChanges)
+                    : outcome === 'success' ? 0 : null,
+                processedPages: result?.batchProgress?.completedBatches
+                    ?? (result ? 1 : 0),
+                knownTotalPages: result?.batchProgress?.totalBatches
+                    ?? (outcome === 'success' ? 1 : null),
+                remainingPages: result?.batchProgress
+                    ? Math.max(0, result.batchProgress.totalBatches
+                        - result.batchProgress.completedBatches)
+                    : outcome === 'success' ? 0 : null,
+                durationMs: now().getTime() - startedAtMs,
+                commandId: input.command?.commandId,
+                errorCode,
+            });
+            activeFailureEvidence = (message, code) => commitTransferEvidence(evidence('error', code), message);
+            try {
+                result = await executePush(attemptOptions, (pushResult) => {
+                    result = pushResult;
+                }, () => {
+                    options.recordTransferEvidence?.(evidence('success'));
+                }, transformTerminalCheckpoint);
+                if (result.emittedEventIds.length > 0) {
+                    options.recordSuppressedRealtimeEventIds?.(result.emittedEventIds);
+                }
+                return result;
+            }
+            catch (error) {
+                if (!failureEvidenceCommitted && options.recordTransferEvidence) {
+                    persist(checkpoint, {
+                        beforeCommit: commitTransferEvidence(evidence('error', String(error?.code || '')), errorMessage(error, 'Workspace sync push failed.')),
+                    });
+                    failureEvidenceCommitted = true;
+                }
+                throw error;
+            }
+            finally {
+                activeFailureEvidence = null;
+            }
+        };
+        try {
+            const resolvedV3Ownership = await resolveV3Ownership({ workspaceId });
+            v3Ownership = {
+                initiativeFeedActivationEnabled: resolvedV3Ownership.initiativeFeedActivationEnabled,
+                initiativeProjection: resolvedV3Ownership.initiativeProjection,
+                combinedFeedActivationEnabled: resolvedV3Ownership.combinedFeedActivationEnabled,
+                combinedProjection: resolvedV3Ownership.combinedProjection,
+                combinedFeedCoverage: resolvedV3Ownership.combinedFeedCoverage,
+                combinedFeedExcludedProjections: resolvedV3Ownership.combinedFeedExcludedProjections,
+            };
+            if (mode === 'pull-only') {
+                const pullResult = checkpoint.syncPhase === 'provision-local'
+                    ? null
+                    : await pull(false, undefined, true);
+                return { checkpoint, result: { pull: pullResult, push: null } };
+            }
+            if (mode === 'push-only') {
+                const pushResult = checkpoint.syncPhase === 'attach-cloud'
+                    ? null
+                    : await push({
+                        forceAllAiProfiles: checkpoint.pendingV2Push
+                            ?.forceAllAiProfiles ?? false,
+                        repairMode: checkpoint.pendingV2Push?.repairMode ?? false,
+                    });
+                return { checkpoint, result: { pull: null, push: pushResult } };
+            }
+            if (mode === 'v2-content-push-only') {
+                const pushResult = checkpoint.syncPhase === 'attach-cloud'
+                    ? null
+                    : await push({
+                        forceAllAiProfiles: false,
+                        repairMode: false,
+                    });
+                return { checkpoint, result: { pull: null, push: pushResult } };
+            }
+            if (mode === 'retry' && checkpoint.retry?.kind === 'repair') {
+                mode = 'repair';
+            }
+            const pushOnlyRetry = mode !== 'repair'
+                && (Boolean(checkpoint.pendingV2Push)
+                    || (mode === 'retry' && (checkpoint.retry?.kind === 'push'
+                        || v2ContentPushRetry)));
+            if (pushOnlyRetry
+                && !v2ContentPushRetry
+                && checkpoint.syncPhase !== 'provision-local'
+                && isLocalWorkspaceSyncPullFairnessDue(checkpoint, now().toISOString())) {
+                await pull(false);
+            }
+            if (mode !== 'repair' && checkpoint.pendingV2Push) {
+                const pushResult = await push({
+                    forceAllAiProfiles: checkpoint.pendingV2Push.forceAllAiProfiles,
+                    repairMode: checkpoint.pendingV2Push.repairMode,
+                });
+                return { checkpoint, result: { pull: null, push: pushResult } };
+            }
+            if (mode === 'retry'
+                && (checkpoint.retry?.kind === 'push'
+                    || checkpoint.retry?.kind === 'v2-content-push')) {
+                const pushResult = await push({
+                    forceAllAiProfiles: false,
+                    repairMode: false,
+                });
+                return { checkpoint, result: { pull: null, push: pushResult } };
+            }
+            if (mode === 'repair') {
+                const earlyContinuation = isFencedRepairContinuation(checkpoint.repairContinuation)
+                    ? checkpoint.repairContinuation
+                    : null;
+                if (earlyContinuation) {
+                    const ownershipFingerprint = repairOwnershipFingerprint(v3Ownership);
+                    if (earlyContinuation.continuationVersion === 1
+                        && earlyContinuation.coordinatorGeneration
+                            === input.coordinatorGeneration
+                        && hasCompletedV3RepairStage(earlyContinuation)) {
+                        persist({
+                            ...checkpoint,
+                            repairContinuation: {
+                                ...earlyContinuation,
+                                continuationVersion: REPAIR_OWNERSHIP_FINGERPRINT_VERSION,
+                                ownershipFingerprint,
+                            },
+                        });
+                    }
+                    else if (earlyContinuation.coordinatorGeneration
+                        !== input.coordinatorGeneration
+                        || earlyContinuation.continuationVersion === 1
+                        || earlyContinuation.ownershipFingerprint !== ownershipFingerprint) {
+                        persist({
+                            ...checkpoint,
+                            repairContinuation: null,
+                            retry: null,
+                        });
+                    }
+                }
+                if (checkpoint.pendingV2Push
+                    && !(isFencedRepairContinuation(checkpoint.repairContinuation)
+                        && checkpoint.repairContinuation.kind === 'final-push')) {
+                    await push({
+                        forceAllAiProfiles: checkpoint.pendingV2Push.forceAllAiProfiles,
+                        repairMode: checkpoint.pendingV2Push.repairMode,
+                    });
+                }
+                let localRecovery = await localServices.prepareOutboxRecovery(workspaceId);
+                if (Number(options.inspectV3Outbox?.().activeDepth || 0) > 0
+                    && options.drainV3Outbox) {
+                    const drainResult = await options.drainV3Outbox({
+                        beforeTransport: () => undefined,
+                    });
+                    if (drainResult === 'v2-content-push-required') {
+                        fail('v2-content-push', 'A referenced attachment must be published before durable repair can continue.', 'SYNC_RUNNER_V2_CONTENT_PUSH_REQUIRED');
+                    }
+                    localRecovery = await localServices.prepareOutboxRecovery(workspaceId);
+                }
+                if (localRecovery.kind === 'recovery'
+                    && localRecovery.state === 'replay_queued') {
+                    localRecovery = await prepareAndDrainRecoveryReplay(localRecovery);
+                }
+                if (localRecovery.kind === 'recovery'
+                    && localRecovery.state === 'replay_queued') {
+                    fail('repair', 'Durable recovery replay must settle before authoritative repair continues.', 'SYNC_RUNNER_RECOVERY_REPLAY_PENDING', RETRY_MAX_DELAY_MS);
+                }
+                if (Number(options.inspectV3Outbox?.().activeDepth || 0) > 0) {
+                    fail('repair', 'Durable local operations must settle before authoritative repair continues.', 'SYNC_RUNNER_RECOVERY_REPLAY_PENDING', RETRY_MAX_DELAY_MS);
+                }
+                const coordinatorRecoveryPlan = options.coordinatorRecovery?.inspectRepairableObligations() || {
+                    total: 0,
+                    requiresV2PushReplay: false,
+                };
+                const repairableCoordinatorObligations = Math.max(0, Math.floor(Number(coordinatorRecoveryPlan.total || 0)));
+                const ownershipFingerprint = repairOwnershipFingerprint(v3Ownership);
+                const recoveryBatchId = localRecovery.kind === 'recovery'
+                    && localRecovery.needsAuthoritativeRepair
+                    ? localRecovery.recoveryBatchId
+                    : null;
+                const forceAuthoritativeRepair = recoveryBatchId !== null
+                    || repairableCoordinatorObligations > 0;
+                let continuation = isFencedRepairContinuation(checkpoint.repairContinuation)
+                    ? checkpoint.repairContinuation
+                    : null;
+                const continuationInvalid = continuation !== null && (continuation.coordinatorGeneration !== input.coordinatorGeneration
+                    || continuation.ownershipFingerprint !== ownershipFingerprint
+                    || (recoveryBatchId !== null
+                        && continuation.recoveryBatchId !== recoveryBatchId)
+                    || (recoveryBatchId !== null
+                        && continuation.kind !== 'v3-combined'
+                        && continuation.kind !== 'v2-reconcile'));
+                if (continuationInvalid || (checkpoint.repairContinuation !== null && !continuation)) {
+                    if (checkpoint.pendingV2Push) {
+                        await push({
+                            forceAllAiProfiles: checkpoint.pendingV2Push.forceAllAiProfiles,
+                            repairMode: checkpoint.pendingV2Push.repairMode,
+                        });
+                    }
+                    persist({
+                        ...checkpoint,
+                        pullCursor: null,
+                        pushBaseline: null,
+                        repairContinuation: null,
+                        retry: null,
+                    });
+                    continuation = null;
+                }
+                if (!continuation) {
+                    const initialContinuation = {
+                        continuationVersion: REPAIR_OWNERSHIP_FINGERPRINT_VERSION,
+                        kind: checkpoint.syncPhase === 'provision-local'
+                            ? 'final-push'
+                            : 'v3-combined',
+                        cursor: null,
+                        attempt: (checkpoint.repairContinuation?.attempt || 0) + 1,
+                        coordinatorGeneration: input.coordinatorGeneration,
+                        ownershipFingerprint,
+                        recoveryBatchId,
+                        forceAuthoritativeRepair,
+                        excludeInitiatives: false,
+                        excludedProjections: [],
+                        completedPushSignatureSha256: null,
+                    };
+                    if (coordinatorRecoveryPlan.requiresV2PushReplay) {
+                        await push({
+                            forceAllAiProfiles: true,
+                            repairMode: true,
+                        }, (committedCheckpoint) => ({
+                            ...committedCheckpoint,
+                            pullCursor: null,
+                            pushBaseline: null,
+                            retry: null,
+                            repairContinuation: initialContinuation,
+                        }));
+                    }
+                    else {
+                        persist({
+                            ...checkpoint,
+                            pullCursor: null,
+                            pushBaseline: null,
+                            pendingV2Push: null,
+                            retry: null,
+                            repairContinuation: initialContinuation,
+                        });
+                    }
+                    continuation = checkpoint.repairContinuation;
+                }
+                if (checkpoint.syncPhase !== 'provision-local'
+                    && (continuation.kind === 'v3-combined'
+                        || continuation.kind === 'v2-reconcile')) {
+                    if (continuation.kind === 'v3-combined') {
+                        const terminalProjection = v3Ownership.combinedFeedActivationEnabled === true
+                            ? 'combined'
+                            : v3Ownership.initiativeFeedActivationEnabled !== undefined
+                                ? 'initiative'
+                                : v3Ownership.combinedFeedActivationEnabled !== undefined
+                                    ? 'combined'
+                                    : null;
+                        const terminalOwner = terminalProjection === 'combined'
+                            ? (v3Ownership.combinedFeedActivationEnabled ? 'v3' : 'v2')
+                            : (v3Ownership.initiativeFeedActivationEnabled ? 'v3' : 'v2');
+                        const plannedExcludeInitiatives = v3Ownership.combinedFeedActivationEnabled === true
+                            ? false
+                            : v3Ownership.initiativeFeedActivationEnabled === true;
+                        const plannedExcludedProjections = v3Ownership.combinedFeedActivationEnabled === true
+                            ? normalizeWorkspaceSyncV2ProjectionExclusions(v3Ownership.combinedFeedExcludedProjections || [])
+                            : [];
+                        transferBoundaryCheckpointTransform = (boundary) => {
+                            const expected = isRecord(boundary.expectedBoundary)
+                                ? boundary.expectedBoundary
+                                : null;
+                            const applyResult = isRecord(boundary.applyResult)
+                                ? boundary.applyResult
+                                : null;
+                            const projection = isRecord(applyResult?.projection)
+                                ? applyResult.projection
+                                : null;
+                            if (!terminalProjection
+                                || expected?.projection !== terminalProjection
+                                || projection?.owner !== terminalOwner
+                                || projection?.repair != null) {
+                                return boundary.checkpoint;
+                            }
+                            return {
+                                ...boundary.checkpoint,
+                                repairContinuation: {
+                                    ...continuation,
+                                    kind: 'v2-reconcile',
+                                    cursor: boundary.checkpoint.pullCursor,
+                                    excludeInitiatives: plannedExcludeInitiatives,
+                                    excludedProjections: plannedExcludedProjections,
+                                },
+                            };
+                        };
+                    }
+                    try {
+                        await pull(true, {
+                            forceAuthoritativeRepair: continuation.forceAuthoritativeRepair,
+                            ...(continuation.recoveryBatchId
+                                ? { recoveryBatchId: continuation.recoveryBatchId }
+                                : {}),
+                        });
+                    }
+                    finally {
+                        transferBoundaryCheckpointTransform = ({ checkpoint: current }) => current;
+                    }
+                    continuation = checkpoint.repairContinuation;
+                }
+                if (continuation.recoveryBatchId) {
+                    const postPullRecovery = await prepareAndDrainRecoveryReplay();
+                    if (postPullRecovery.kind === 'recovery'
+                        || Number(options.inspectV3Outbox?.().activeDepth || 0) > 0) {
+                        fail('repair', 'Durable recovery replay must settle before authoritative repair continues.', 'SYNC_RUNNER_RECOVERY_REPLAY_PENDING', RETRY_MAX_DELAY_MS);
+                    }
+                }
+                let pushResult = null;
+                if (continuation.kind === 'final-push') {
+                    pushResult = await push({
+                        forceAllAiProfiles: true,
+                        repairMode: true,
+                    }, (committedCheckpoint, _result, signature) => ({
+                        ...committedCheckpoint,
+                        repairContinuation: {
+                            ...continuation,
+                            kind: 'settlement',
+                            completedPushSignatureSha256: createHash('sha256')
+                                .update(signature)
+                                .digest('hex'),
+                        },
+                    }));
+                    continuation = checkpoint.repairContinuation;
+                    if (continuation.kind !== 'settlement'
+                        || !continuation.completedPushSignatureSha256) {
+                        fail('repair', 'Server-owned authoritative repair did not atomically retain its push signature.', 'SYNC_RUNNER_COORDINATOR_RECOVERY_SETTLEMENT_UNAVAILABLE', RETRY_MAX_DELAY_MS);
+                    }
+                }
+                if (continuation.kind !== 'settlement') {
+                    throw new WorkspaceSyncEngineServerRunnerOperationError(`Authoritative repair cannot settle from ${continuation.kind}.`, 'SYNC_RUNNER_REPAIR_CONTINUATION_INVALID');
+                }
+                const currentOwnership = await resolveV3Ownership({ workspaceId });
+                if (repairOwnershipFingerprint(currentOwnership) !== ownershipFingerprint) {
+                    persist({
+                        ...checkpoint,
+                        repairContinuation: null,
+                        retry: null,
+                    });
+                    fail('repair', 'Workspace sync ownership changed before authoritative repair settlement.', 'SYNC_RUNNER_V3_OWNERSHIP_CHANGED');
+                }
+                const currentCoordinatorRecoveryPlan = options.coordinatorRecovery?.inspectRepairableObligations() || {
+                    total: 0,
+                    requiresV2PushReplay: false,
+                };
+                if (currentCoordinatorRecoveryPlan.total > 0) {
+                    const coordinatorRecovery = options.coordinatorRecovery;
+                    if (!coordinatorRecovery) {
+                        fail('repair', 'Server-owned authoritative repair could not settle coordinator recovery.', 'SYNC_RUNNER_COORDINATOR_RECOVERY_SETTLEMENT_UNAVAILABLE', RETRY_MAX_DELAY_MS);
+                    }
+                    if (!continuation.completedPushSignatureSha256) {
+                        fail('repair', 'Server-owned authoritative repair did not retain its push signature.', 'SYNC_RUNNER_COORDINATOR_RECOVERY_SETTLEMENT_UNAVAILABLE', RETRY_MAX_DELAY_MS);
+                    }
+                    const authoritativeRecovery = coordinatorRecovery;
+                    const stateSignatureSha256 = continuation.completedPushSignatureSha256;
+                    const completion = authoritativeRecovery.completeAuthoritativeRepair({
+                        repairId: input.command?.commandId
+                            || `server-repair-${stateSignatureSha256}`,
+                        stateSignatureSha256,
+                    });
+                    if (completion.remainingRepairable > 0) {
+                        fail('repair', `${completion.remainingRepairable} coordinator recovery obligation(s) remain after authoritative repair.`, 'SYNC_RUNNER_COORDINATOR_RECOVERY_INCOMPLETE', RETRY_MAX_DELAY_MS);
+                    }
+                }
+                persist({
+                    ...checkpoint,
+                    repairContinuation: null,
+                    retry: null,
+                    lastError: null,
+                });
+                return { checkpoint, result: { repaired: true, push: pushResult } };
+            }
+            const pullResult = checkpoint.syncPhase === 'provision-local'
+                ? null
+                : await pull(false);
+            const pushResult = checkpoint.syncPhase === 'attach-cloud'
+                ? null
+                : await push({
+                    forceAllAiProfiles: false,
+                    repairMode: false,
+                });
+            return { checkpoint, result: { pull: pullResult, push: pushResult } };
+        }
+        catch (error) {
+            if (error instanceof WorkspaceSyncEngineServerRunnerOperationError)
+                throw error;
+            const message = errorMessage(error, 'Workspace sync runner operation failed.');
+            setRetry(activeRetryKind, message);
+            throw error;
+        }
+    };
+    return {
+        sync: (input) => execute(input, 'sync'),
+        retry: (input) => execute(input, 'retry'),
+        repair: (input) => execute(input, 'repair'),
+        pull: (input) => execute(input, 'pull-only'),
+        push: (input) => execute(input, 'push-only'),
+        pushContentPrerequisite: (input) => execute(input, 'v2-content-push-only'),
+    };
+}