@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/coordinator/localSyncExecutionPermitTypes.d.ts

@@ -0,0 +1,52 @@
+export type LocalSyncExecutionPermitState = 'issued-idle' | 'gateway-in-flight' | 'gateway-complete-awaiting-apply' | 'local-commit-entered' | 'released' | 'abandoned-reconcile-required' | 'abandoned-clean';
+export type LocalSyncUpstreamDisposition = 'not-started' | 'accepted' | 'rejected' | 'unknown';
+export type LocalSyncGatewayOperationClass = 'handshake' | 'bootstrap' | 'push' | 'pull' | 'repair' | 'v3-dispatch' | 'local-apply';
+export type LocalSyncExecutionPermitOwnerMode = 'browser-gateway' | 'server';
+export interface LocalSyncExecutionPermit {
+    permitId: string;
+    workspaceId: string;
+    coordinatorGeneration: number;
+    serverInstanceId: string;
+    ownerMode: LocalSyncExecutionPermitOwnerMode;
+    operationClass: LocalSyncGatewayOperationClass;
+    operationIdentity: string | null;
+    lastCommittedCursor: unknown | null;
+    state: LocalSyncExecutionPermitState;
+    upstreamDisposition: LocalSyncUpstreamDisposition | null;
+    issuedAt: string;
+    deadlineAt: string;
+    lastTransitionAt: string;
+    completedAt: string | null;
+    errorCode: string | null;
+}
+export interface LocalSyncRecoveryObligation {
+    obligationId: string;
+    permitId: string;
+    workspaceId: string;
+    operationClass: LocalSyncGatewayOperationClass;
+    operationIdentity: string | null;
+    upstreamDisposition: LocalSyncUpstreamDisposition;
+    lastCommittedCursor: unknown | null;
+    requiredAction: 'replay-operation-then-reconcile' | 'refetch-from-committed-cursor';
+    createdAt: string;
+    resolvedAt: string | null;
+    resolvedBoundary: unknown | null;
+}
+export interface LocalSyncExecutionPermitDrainSnapshot {
+    workspaceId: string;
+    coordinatorGeneration: number;
+    active: number;
+    byState: Partial<Record<LocalSyncExecutionPermitState, number>>;
+    permits: LocalSyncExecutionPermit[];
+    truncated: boolean;
+    cleanAbandonEligible: number;
+    recoveryObligations: number;
+}
+export interface LocalSyncExecutionPermitCleanAbandonResult {
+    abandonedPermitIds: string[];
+    remainingEligible: number;
+}
+export declare class LocalSyncExecutionPermitError extends Error {
+    readonly code: 'SYNC_COORDINATOR_STALE_GENERATION' | 'SYNC_COORDINATOR_INACTIVE_WORKSPACE' | 'SYNC_COORDINATOR_PERMITS_DISABLED' | 'SYNC_COORDINATOR_PERMIT_NOT_FOUND' | 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT' | 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT' | 'SYNC_COORDINATOR_PERMIT_SERVER_MISMATCH' | 'SYNC_COORDINATOR_PERMIT_EXPIRED' | 'SYNC_COORDINATOR_LOCAL_COMMIT_INVARIANT';
+    constructor(message: string, code: 'SYNC_COORDINATOR_STALE_GENERATION' | 'SYNC_COORDINATOR_INACTIVE_WORKSPACE' | 'SYNC_COORDINATOR_PERMITS_DISABLED' | 'SYNC_COORDINATOR_PERMIT_NOT_FOUND' | 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT' | 'SYNC_COORDINATOR_PERMIT_IDENTITY_CONFLICT' | 'SYNC_COORDINATOR_PERMIT_SERVER_MISMATCH' | 'SYNC_COORDINATOR_PERMIT_EXPIRED' | 'SYNC_COORDINATOR_LOCAL_COMMIT_INVARIANT');
+}

package/dist/sync/coordinator/localSyncExecutionPermitTypes.js

@@ -0,0 +1,8 @@
+export class LocalSyncExecutionPermitError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'LocalSyncExecutionPermitError';
+    }
+}

package/dist/sync/coordinator/localSyncOwnershipDrainBarrier.d.ts

@@ -0,0 +1,33 @@
+import type { LocalSyncExecutionPermitDrainSnapshot } from './localSyncExecutionPermitTypes.js';
+import type { LocalSyncExecutionPermitStore } from './localSyncExecutionPermitStore.js';
+import type { LocalSyncDispatchTracker } from './localSyncDispatchTracker.js';
+import type { WorkspaceSyncTransportGateway } from './workspaceSyncTransportGateway.js';
+export interface LocalSyncOwnershipDrainResult {
+    workspaceId: string;
+    sourceGeneration: number;
+    cleanAbandoned: number;
+    reconcileRequired: number;
+    recoveryObligations: number;
+}
+export declare class LocalSyncOwnershipDrainError extends Error {
+    readonly snapshot: LocalSyncExecutionPermitDrainSnapshot;
+    readonly code = "SYNC_COORDINATOR_OWNERSHIP_DRAIN_BLOCKED";
+    constructor(message: string, snapshot: LocalSyncExecutionPermitDrainSnapshot);
+}
+export declare class LocalSyncOwnershipDrainBarrier {
+    private readonly options;
+    constructor(options: {
+        permitStore: Pick<LocalSyncExecutionPermitStore, 'inspectGenerationDrain' | 'abandonNeverStartedForDrain' | 'abandonPermit'>;
+        transportGateway: Pick<WorkspaceSyncTransportGateway, 'drain'>;
+        dispatchTracker: Pick<LocalSyncDispatchTracker, 'drain'>;
+        serverInstanceId: string;
+        nowMs?: () => number;
+        wait?: (delayMs: number) => Promise<void>;
+        pollIntervalMs?: number;
+    });
+    drain(input: {
+        workspaceId: string;
+        sourceGeneration: number;
+        graceMs: number;
+    }): Promise<LocalSyncOwnershipDrainResult>;
+}

package/dist/sync/coordinator/localSyncOwnershipDrainBarrier.js

@@ -0,0 +1,83 @@
+export class LocalSyncOwnershipDrainError extends Error {
+    snapshot;
+    code = 'SYNC_COORDINATOR_OWNERSHIP_DRAIN_BLOCKED';
+    constructor(message, snapshot) {
+        super(message);
+        this.snapshot = snapshot;
+        this.name = 'LocalSyncOwnershipDrainError';
+    }
+}
+export class LocalSyncOwnershipDrainBarrier {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async drain(input) {
+        const nowMs = this.options.nowMs || Date.now;
+        const wait = this.options.wait || ((delayMs) => new Promise((resolve) => {
+            const timer = setTimeout(resolve, delayMs);
+            timer.unref?.();
+        }));
+        const graceMs = Math.max(0, Math.floor(input.graceMs));
+        const deadlineMs = nowMs() + graceMs;
+        let cleanAbandoned = 0;
+        let reconcileRequired = 0;
+        while (true) {
+            const abandoned = this.options.permitStore.abandonNeverStartedForDrain({
+                workspaceId: input.workspaceId,
+                coordinatorGeneration: input.sourceGeneration,
+                limit: 500,
+            });
+            cleanAbandoned += abandoned.abandonedPermitIds.length;
+            if (abandoned.remainingEligible === 0)
+                break;
+        }
+        const remainingForExternalDrain = Math.max(0, deadlineMs - nowMs());
+        await Promise.all([
+            this.options.transportGateway.drain(remainingForExternalDrain),
+            this.options.dispatchTracker.drain(remainingForExternalDrain),
+        ]);
+        const pollIntervalMs = Math.max(1, Math.floor(this.options.pollIntervalMs ?? 25));
+        while (true) {
+            const snapshot = this.options.permitStore.inspectGenerationDrain({
+                workspaceId: input.workspaceId,
+                coordinatorGeneration: input.sourceGeneration,
+                limit: 500,
+            });
+            if (snapshot.active === 0) {
+                return {
+                    workspaceId: input.workspaceId,
+                    sourceGeneration: input.sourceGeneration,
+                    cleanAbandoned,
+                    reconcileRequired,
+                    recoveryObligations: snapshot.recoveryObligations,
+                };
+            }
+            const remainingMs = deadlineMs - nowMs();
+            if (remainingMs > 0) {
+                await wait(Math.min(pollIntervalMs, remainingMs));
+                continue;
+            }
+            let terminalized = 0;
+            for (const permit of snapshot.permits) {
+                if (permit.state !== 'gateway-complete-awaiting-apply')
+                    continue;
+                const result = this.options.permitStore.abandonPermit({
+                    permitId: permit.permitId,
+                    workspaceId: input.workspaceId,
+                    coordinatorGeneration: input.sourceGeneration,
+                    serverInstanceId: this.options.serverInstanceId,
+                    errorCode: 'SYNC_COORDINATOR_OWNERSHIP_DRAIN_TIMEOUT',
+                });
+                terminalized += 1;
+                if (result.state === 'abandoned-clean')
+                    cleanAbandoned += 1;
+                if (result.state === 'abandoned-reconcile-required')
+                    reconcileRequired += 1;
+            }
+            if (terminalized > 0)
+                continue;
+            throw new LocalSyncOwnershipDrainError('Local sync ownership transfer is blocked by nonterminal source-generation work.', snapshot);
+        }
+    }
+}

package/dist/sync/coordinator/localSyncPermitTransactionHooks.d.ts

@@ -0,0 +1,9 @@
+import type { WorkspaceSyncEngineApplyTransactionHooks } from '../engine/workspaceSyncEngineV3LocalFeedApply.js';
+import { type WorkspaceSyncEngineTransferBoundaryCommitter, type WorkspaceSyncEngineTransferCompletionGroup } from '../engine/workspaceSyncEngineTransferCompletion.js';
+import { LocalSyncExecutionPermitStore } from './localSyncExecutionPermitStore.js';
+export declare function createLocalSyncPermitTransactionHooks(input: {
+    permitStore: LocalSyncExecutionPermitStore;
+    completionGroup: WorkspaceSyncEngineTransferCompletionGroup;
+    commitBoundary: WorkspaceSyncEngineTransferBoundaryCommitter;
+    recordCommittedLocalApply?: (applyResult: unknown) => void;
+}): WorkspaceSyncEngineApplyTransactionHooks;

package/dist/sync/coordinator/localSyncPermitTransactionHooks.js

@@ -0,0 +1,27 @@
+import { assertWorkspaceSyncEngineTransferBoundary, validateWorkspaceSyncEngineTransferCompletionGroup, } from '../engine/workspaceSyncEngineTransferCompletion.js';
+import { canonicalWorkspaceSyncJson } from '../v3/canonicalWorkspaceSyncJson.js';
+export function createLocalSyncPermitTransactionHooks(input) {
+    validateWorkspaceSyncEngineTransferCompletionGroup(input.completionGroup);
+    const completionGroup = {
+        ...input.completionGroup,
+        permitIds: Object.freeze([...input.completionGroup.permitIds]),
+        previousBoundary: JSON.parse(canonicalWorkspaceSyncJson(input.completionGroup.previousBoundary)),
+        expectedBoundary: JSON.parse(canonicalWorkspaceSyncJson(input.completionGroup.expectedBoundary)),
+    };
+    return {
+        beforeApply: () => {
+            input.permitStore.enterLocalCommitGroup(completionGroup);
+        },
+        beforeCommit: (applyResult) => {
+            input.permitStore.completeLocalCommitGroup(completionGroup, () => {
+                const committedBoundary = input.commitBoundary({
+                    previousBoundary: completionGroup.previousBoundary,
+                    expectedBoundary: completionGroup.expectedBoundary,
+                    applyResult,
+                });
+                assertWorkspaceSyncEngineTransferBoundary(committedBoundary, completionGroup.expectedBoundary);
+                input.recordCommittedLocalApply?.(applyResult);
+            });
+        },
+    };
+}

package/dist/sync/coordinator/localSyncProcessLock.d.ts

@@ -0,0 +1,12 @@
+import { type LocalSyncProcessLockIdentityInput } from '../../server/localDatabaseIdentity.js';
+export { resolveLocalSyncProcessLockIdentity } from '../../server/localDatabaseIdentity.js';
+export type { LocalSyncProcessLockIdentityInput } from '../../server/localDatabaseIdentity.js';
+export interface LocalSyncProcessLock {
+    readonly endpoint: string;
+    readonly ownershipKey: string;
+    readonly serviceGeneration?: string | null;
+    readonly owned: boolean;
+    release(): Promise<void>;
+}
+export declare function isAcquiredOwnedLocalSyncProcessLock(lock: LocalSyncProcessLock): boolean;
+export declare function acquireLocalSyncProcessLock(input: LocalSyncProcessLockIdentityInput): Promise<LocalSyncProcessLock>;

package/dist/sync/coordinator/localSyncProcessLock.js

@@ -0,0 +1,212 @@
+import * as fs from 'fs';
+import * as net from 'net';
+import { resolveLocalSyncProcessLockIdentity, } from '../../server/localDatabaseIdentity.js';
+export { resolveLocalSyncProcessLockIdentity } from '../../server/localDatabaseIdentity.js';
+const LOCK_PROBE_TIMEOUT_MS = 750;
+const STALE_REBIND_ATTEMPTS = 30;
+const STALE_REBIND_DELAY_MS = 100;
+const acquiredOwnedProcessLocks = new WeakSet();
+export function isAcquiredOwnedLocalSyncProcessLock(lock) {
+    return acquiredOwnedProcessLocks.has(lock) && lock.owned;
+}
+function listen(server, endpoint) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(endpoint);
+    });
+}
+function probe(endpoint, ownershipKey) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection(endpoint);
+        let settled = false;
+        let response = '';
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.once('close', () => resolve(result));
+            socket.destroy();
+        };
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            response += chunk;
+            if (response.length > 512) {
+                finish({ status: 'indeterminate', serviceGeneration: null });
+            }
+        });
+        socket.once('end', () => {
+            const prefix = `TASKFORCE_SYNC_LOCK:${ownershipKey}:`;
+            if (!response.startsWith(prefix)) {
+                finish({ status: 'indeterminate', serviceGeneration: null });
+                return;
+            }
+            finish({
+                status: 'live',
+                serviceGeneration: response.slice(prefix.length) || null,
+            });
+        });
+        socket.once('error', (error) => {
+            finish({
+                status: error.code === 'ECONNREFUSED' || error.code === 'ENOENT'
+                    ? 'stale'
+                    : 'indeterminate',
+                serviceGeneration: null,
+            });
+        });
+        socket.setTimeout(LOCK_PROBE_TIMEOUT_MS, () => finish({
+            status: 'indeterminate',
+            serviceGeneration: null,
+        }));
+    });
+}
+function assertMatchingServiceGeneration(expectedGeneration, probeResult) {
+    if (!expectedGeneration)
+        return;
+    if (probeResult.status !== 'live' || probeResult.serviceGeneration !== expectedGeneration) {
+        throw new Error('Local sync lock service generation does not match the service lease.');
+    }
+}
+async function closeServer(server) {
+    if (!server.listening)
+        return;
+    await new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+    });
+}
+function readPosixSocketIdentity(endpoint) {
+    try {
+        const stat = fs.lstatSync(endpoint);
+        if (!stat.isSocket()) {
+            throw new Error(`Refusing to remove non-socket local sync lock endpoint: ${endpoint}`);
+        }
+        return { dev: stat.dev, ino: stat.ino };
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function removeStalePosixEndpoint(endpoint, expectedIdentity) {
+    if (!expectedIdentity)
+        return false;
+    const currentIdentity = readPosixSocketIdentity(endpoint);
+    if (!currentIdentity
+        || currentIdentity.dev !== expectedIdentity.dev
+        || currentIdentity.ino !== expectedIdentity.ino) {
+        return false;
+    }
+    fs.unlinkSync(endpoint);
+    return true;
+}
+export async function acquireLocalSyncProcessLock(input) {
+    const identity = resolveLocalSyncProcessLockIdentity(input);
+    const platform = input.platform || process.platform;
+    if (platform !== 'win32' && fs.existsSync(identity.endpoint)) {
+        const socketIdentity = readPosixSocketIdentity(identity.endpoint);
+        const probeResult = await probe(identity.endpoint, identity.ownershipKey);
+        if (probeResult.status !== 'stale') {
+            assertMatchingServiceGeneration(input.serviceGeneration, probeResult);
+            return {
+                ...identity,
+                serviceGeneration: probeResult.serviceGeneration,
+                owned: false,
+                async release() { },
+            };
+        }
+        removeStalePosixEndpoint(identity.endpoint, socketIdentity);
+    }
+    for (let attempt = 0; attempt < STALE_REBIND_ATTEMPTS; attempt += 1) {
+        const server = net.createServer((socket) => {
+            // A contender only needs the successful connection to prove that this
+            // owner is live, so it may close before this diagnostic response is
+            // written. Treat that peer disconnect as a completed probe instead of
+            // allowing an EPIPE socket error to terminate the owner process.
+            socket.on('error', () => socket.destroy());
+            socket.end([
+                'TASKFORCE_SYNC_LOCK',
+                identity.ownershipKey,
+                input.serviceGeneration || '',
+            ].join(':'));
+        });
+        server.unref();
+        try {
+            await listen(server, identity.endpoint);
+            let owned = true;
+            let releasePromise = null;
+            const socketIdentity = platform === 'win32'
+                ? null
+                : readPosixSocketIdentity(identity.endpoint);
+            const acquiredLock = {
+                ...identity,
+                serviceGeneration: input.serviceGeneration || null,
+                get owned() {
+                    return owned;
+                },
+                async release() {
+                    if (releasePromise)
+                        return releasePromise;
+                    releasePromise = (async () => {
+                        try {
+                            await closeServer(server);
+                            if (platform !== 'win32') {
+                                removeStalePosixEndpoint(identity.endpoint, socketIdentity);
+                            }
+                        }
+                        finally {
+                            owned = false;
+                        }
+                    })();
+                    return releasePromise;
+                },
+            };
+            acquiredOwnedProcessLocks.add(acquiredLock);
+            return acquiredLock;
+        }
+        catch (error) {
+            server.close();
+            const code = error?.code;
+            if (code !== 'EADDRINUSE')
+                throw error;
+            const socketIdentity = platform === 'win32'
+                ? null
+                : readPosixSocketIdentity(identity.endpoint);
+            const probeResult = await probe(identity.endpoint, identity.ownershipKey);
+            if (probeResult.status !== 'stale') {
+                assertMatchingServiceGeneration(input.serviceGeneration, probeResult);
+                return {
+                    ...identity,
+                    serviceGeneration: probeResult.serviceGeneration,
+                    owned: false,
+                    async release() { },
+                };
+            }
+            if (platform === 'win32' || attempt === STALE_REBIND_ATTEMPTS - 1) {
+                return {
+                    ...identity,
+                    serviceGeneration: input.serviceGeneration || null,
+                    owned: false,
+                    async release() { },
+                };
+            }
+            removeStalePosixEndpoint(identity.endpoint, socketIdentity);
+            await new Promise((resolve) => setTimeout(resolve, STALE_REBIND_DELAY_MS));
+        }
+    }
+    return {
+        ...identity,
+        serviceGeneration: input.serviceGeneration || null,
+        owned: false,
+        async release() { },
+    };
+}

package/dist/sync/coordinator/localSyncV3DispatchRecoveryReconciler.d.ts

@@ -0,0 +1,17 @@
+import { WorkspaceSyncDurabilityStore } from '../v3/syncDurabilityStore.js';
+import type { LocalSyncExecutionPermitOwnerMode } from './localSyncExecutionPermitTypes.js';
+import { LocalSyncExecutionPermitStore } from './localSyncExecutionPermitStore.js';
+export declare function reconcileSettledV3DispatchRecoveryObligations(input: {
+    permitStore: LocalSyncExecutionPermitStore;
+    durabilityStore: WorkspaceSyncDurabilityStore;
+    workspaceId: string;
+    coordinatorGeneration: number;
+    ownerMode: LocalSyncExecutionPermitOwnerMode;
+    now?: () => string;
+}): {
+    examined: number;
+    resolved: number;
+    replayQueued: number;
+    unproven: number;
+    malformed: number;
+};

package/dist/sync/coordinator/localSyncV3DispatchRecoveryReconciler.js

@@ -0,0 +1,82 @@
+function parseOperationIdentity(value, workspaceId) {
+    const parts = value.split('/');
+    if (parts.length !== 4
+        || parts.some((part) => !part)
+        || parts[1] !== workspaceId) {
+        return null;
+    }
+    return {
+        tenantId: parts[0],
+        workspaceId: parts[1],
+        clientId: parts[2],
+        operationId: parts[3],
+    };
+}
+function boundaryFor(operationIdentity, evidence) {
+    if (evidence.kind === 'accepted') {
+        return {
+            version: 1,
+            kind: 'accepted-v3-dispatch',
+            operationIdentity,
+            acceptedSequence: evidence.acceptedSequence,
+        };
+    }
+    return {
+        version: 1,
+        kind: 'completed-v3-dispatch-recovery',
+        operationIdentity,
+        recoveryBatchId: evidence.recoveryBatchId,
+        baselineMarker: evidence.baselineMarker,
+        completedAt: evidence.completedAt,
+    };
+}
+export function reconcileSettledV3DispatchRecoveryObligations(input) {
+    const obligations = input.permitStore.listOpenRecoveryObligations(input.workspaceId).filter((obligation) => (obligation.operationClass === 'v3-dispatch'
+        && obligation.requiredAction === 'replay-operation-then-reconcile'));
+    const resolutions = [];
+    let malformed = 0;
+    let unproven = 0;
+    let replayQueued = 0;
+    for (const obligation of obligations) {
+        const operationIdentity = String(obligation.operationIdentity || '');
+        const identity = parseOperationIdentity(operationIdentity, input.workspaceId);
+        if (!identity) {
+            malformed += 1;
+            continue;
+        }
+        const evidence = input.durabilityStore
+            .readV3DispatchSettlementEvidence(identity);
+        if (!evidence) {
+            if (obligation.upstreamDisposition === 'accepted'
+                && input.durabilityStore.requeueAcceptedV3DispatchOperation({
+                    identity,
+                    now: (input.now || (() => new Date().toISOString()))(),
+                })) {
+                replayQueued += 1;
+                continue;
+            }
+            unproven += 1;
+            continue;
+        }
+        resolutions.push({
+            obligationId: obligation.obligationId,
+            operationIdentity,
+            resolvedBoundary: boundaryFor(operationIdentity, evidence),
+        });
+    }
+    if (resolutions.length > 0) {
+        input.permitStore.resolveV3DispatchRecoveryObligations({
+            workspaceId: input.workspaceId,
+            coordinatorGeneration: input.coordinatorGeneration,
+            ownerMode: input.ownerMode,
+            resolutions,
+        });
+    }
+    return {
+        examined: obligations.length,
+        resolved: resolutions.length,
+        replayQueued,
+        unproven,
+        malformed,
+    };
+}

package/dist/sync/coordinator/localWorkspaceSyncRunner.d.ts

@@ -0,0 +1,134 @@
+import type { LocalSyncCoordinatorCommandRecord } from './localSyncCoordinatorTypes.js';
+import type { LocalSyncCoordinatorStore } from './localSyncCoordinatorStore.js';
+import { type LocalWorkspaceSyncRunnerCheckpoint, type LocalWorkspaceSyncRunnerState, type LocalWorkspaceSyncRunnerStateStore } from './localWorkspaceSyncRunnerState.js';
+import type { WorkspaceSyncCredentialBroker } from './workspaceSyncCredentialBroker.js';
+export interface LocalWorkspaceSyncRunnerOperationInput {
+    command: LocalSyncCoordinatorCommandRecord | null;
+    coordinatorGeneration: number;
+    checkpoint: LocalWorkspaceSyncRunnerCheckpoint;
+    checkpointRevision: number;
+    persistCheckpoint(checkpoint: LocalWorkspaceSyncRunnerCheckpoint, options?: {
+        beforeCommit?: () => void;
+    }): LocalWorkspaceSyncRunnerPersistedCheckpoint;
+    now: string;
+}
+export interface LocalWorkspaceSyncRunnerPersistedCheckpoint {
+    checkpoint: LocalWorkspaceSyncRunnerCheckpoint;
+    checkpointRevision: number;
+}
+export interface LocalWorkspaceSyncRunnerOperationResult {
+    checkpoint: LocalWorkspaceSyncRunnerCheckpoint;
+    result?: unknown;
+}
+export interface LocalWorkspaceSyncRunnerOperations {
+    sync(input: LocalWorkspaceSyncRunnerOperationInput): Promise<LocalWorkspaceSyncRunnerOperationResult>;
+    retry(input: LocalWorkspaceSyncRunnerOperationInput): Promise<LocalWorkspaceSyncRunnerOperationResult>;
+    repair(input: LocalWorkspaceSyncRunnerOperationInput): Promise<LocalWorkspaceSyncRunnerOperationResult>;
+    pull(input: LocalWorkspaceSyncRunnerOperationInput): Promise<LocalWorkspaceSyncRunnerOperationResult>;
+    push(input: LocalWorkspaceSyncRunnerOperationInput): Promise<LocalWorkspaceSyncRunnerOperationResult>;
+    pushContentPrerequisite(input: LocalWorkspaceSyncRunnerOperationInput): Promise<LocalWorkspaceSyncRunnerOperationResult>;
+}
+export type LocalWorkspaceSyncFairPushResult<T> = {
+    kind: 'dispatched';
+    result: T;
+} | {
+    kind: 'pull-required';
+} | {
+    kind: 'command-pending';
+} | {
+    kind: 'disabled';
+};
+export interface LocalWorkspaceSyncRunnerContext {
+    tenantId: string;
+    workspaceId: string;
+    coordinatorGeneration: number;
+}
+export interface LocalWorkspaceSyncRunnerStatus {
+    running: boolean;
+    prepared: boolean;
+    acceptingWork: boolean;
+    lifecycleToken: number;
+    queuedCommandCount: number;
+    checkpoint: LocalWorkspaceSyncRunnerState | null;
+}
+export declare class LocalWorkspaceSyncRunnerError extends Error {
+    readonly code: 'SYNC_RUNNER_NOT_STARTED' | 'SYNC_RUNNER_ALREADY_STARTED' | 'SYNC_RUNNER_COORDINATOR_FENCE_INVALID' | 'SYNC_RUNNER_COMMAND_INVALID' | 'SYNC_RUNNER_COMMAND_DISABLED' | 'SYNC_RUNNER_DRAIN_TIMEOUT';
+    constructor(message: string, code: 'SYNC_RUNNER_NOT_STARTED' | 'SYNC_RUNNER_ALREADY_STARTED' | 'SYNC_RUNNER_COORDINATOR_FENCE_INVALID' | 'SYNC_RUNNER_COMMAND_INVALID' | 'SYNC_RUNNER_COMMAND_DISABLED' | 'SYNC_RUNNER_DRAIN_TIMEOUT');
+}
+export declare class LocalWorkspaceSyncRunner {
+    private readonly options;
+    private context;
+    private queueTail;
+    private commandExecutions;
+    private retryTimer;
+    private acceptedCommandWatchdogTimer;
+    private lifecycleToken;
+    private prepared;
+    private activated;
+    private acceptingWork;
+    private terminated;
+    constructor(options: {
+        coordinatorStore: Pick<LocalSyncCoordinatorStore, 'readOrCreateState' | 'readCommand' | 'claimNextRunnerCommand' | 'listAcceptedRunnerCommands' | 'recoverRunnerCommandsForRecreation' | 'finishCommand'>;
+        runnerStateStore: LocalWorkspaceSyncRunnerStateStore;
+        credentialBroker: Pick<WorkspaceSyncCredentialBroker, 'readSnapshot' | 'requireCapability'>;
+        operations: LocalWorkspaceSyncRunnerOperations;
+        recoverBeforeStart?: (context: LocalWorkspaceSyncRunnerContext) => Promise<void>;
+        drainBarrier?: (context: LocalWorkspaceSyncRunnerContext, graceMs: number) => Promise<void>;
+        now?: () => string;
+        setTimer?: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+        clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+        defaultDrainGraceMs?: number;
+        acceptedCommandWatchdogMs?: number;
+        requestScheduledRetryWake?: (context: LocalWorkspaceSyncRunnerContext) => void;
+        reportInternalError?: (error: unknown, source: 'credential-wake' | 'activation-wake' | 'scheduled-retry' | 'command-watchdog') => void;
+    });
+    start(context: LocalWorkspaceSyncRunnerContext): Promise<void>;
+    prepare(context: LocalWorkspaceSyncRunnerContext): Promise<void>;
+    activate(): void;
+    executeCommand(commandId: string): Promise<LocalSyncCoordinatorCommandRecord | null>;
+    inspect(): Promise<void>;
+    pullDue(): Promise<void>;
+    retryDue(): Promise<void>;
+    pushDue(): Promise<void>;
+    pushContentPrerequisiteDue(): Promise<void>;
+    observeRemoteHint(observedAt?: string): Promise<void>;
+    dispatchPushWithFairness<T extends {
+        claimed: number;
+    }>(dispatch: (beforeTransport: () => void) => Promise<T>, options?: {
+        ignoreAcceptedCommandId?: string;
+        ignorePullFairness?: boolean;
+    }): Promise<LocalWorkspaceSyncFairPushResult<T>>;
+    notifyCredentialAvailable(): void;
+    drain(graceMs: number): Promise<void>;
+    stop(): Promise<void>;
+    readStatus(): LocalWorkspaceSyncRunnerStatus;
+    private executeClaimedCommandWithFailureBoundary;
+    private drainAcceptedCommands;
+    private executeClaimedCommand;
+    private runInspection;
+    private deferForAuth;
+    private completeFailure;
+    private schedulePersistedRetry;
+    private scheduleAcceptedCommandWatchdog;
+    private drainAcceptedCommandsWithoutRequestedCommand;
+    private wakeAcceptedCommands;
+    private runScheduledRetry;
+    private createOperationCheckpointPort;
+    private hasExactCapability;
+    private validateCommand;
+    private assertCoordinatorFence;
+    private assertPreparationFence;
+    private readRunnerState;
+    private enqueue;
+    private settleInternal;
+    private terminateForStaleFence;
+    private requireStarted;
+    private requirePrepared;
+    private resetAfterPreparationFailure;
+    private now;
+    private setTimer;
+    private clearTimer;
+    private clearRetryTimer;
+    private clearAcceptedCommandWatchdogTimer;
+    private clearRunnerTimers;
+}