/**
 * Automatic main-brain sync (T13468): `cleo cloud sync` without the user
 * typing it. Runs from hooks CLEO already has, never a daemon or server of
 * its own:
 *
 *   - session end: the detached session-end worker
 *     (`sessions/session-end-snapshot.ts`), after its snapshot;
 *   - the sentient tick (`sentient/tick.ts`), at most once per
 *     {@link autoSyncIntervalMs};
 *   - a normal CLI command in a linked project (T13553,
 *     `cloud/auto-sync-command.ts`): a detached child, same interval.
 *
 * Best-effort and bounded: a store with no sync flag on, a signed-out
 * device or an unlinked project is a quiet skip; any other failure
 * (offline, refused) is recorded in `<CLEO_HOME>/auto-sync.json`, which
 * `cleo cloud status` reports as one {@link W_AUTO_SYNC_FAILED} warning.
 * Single-flight across processes under a lock, admitted by the governor as
 * `db-heavy` (skipped, not queued, under pressure). Never throws.
 *
 * @task T13468
 */
import type { CloudWarning } from '@cleocode/contracts';
/** Default minimum gap between tick-driven syncs. */
export declare const AUTO_SYNC_INTERVAL_MS: number;
/** Minimum gap between session-end syncs: coalesces a burst of session ends. */
export declare const AUTO_SYNC_SESSION_END_MIN_MS = 60000;
/** Upper bound on one automatic sync. */
export declare const AUTO_SYNC_TIMEOUT_MS = 120000;
/** Warning code `cleo cloud status` shows for a failed automatic sync. */
export declare const W_AUTO_SYNC_FAILED = "W_AUTO_SYNC_FAILED";
/** What triggered an automatic sync. */
export type AutoSyncReason = 'session-end' | 'tick' | 'command';
/** Persisted state of automatic sync. */
export interface AutoSyncState {
    /** When the last attempt started (ISO), else absent. */
    lastAttemptAt?: string;
    /** When the last attempt succeeded (ISO), else absent. */
    lastOkAt?: string;
    /** The last failure, cleared by a success. */
    lastError?: {
        at: string;
        code: string;
        message: string;
    } | null;
}
/** Outcome of {@link autoCloudSync}. */
export type AutoSyncOutcome = 'synced' | 'throttled' | 'disabled' | 'skipped' | 'busy' | 'deferred' | 'failed';
/** Test seams for {@link autoCloudSync}. */
export interface AutoSyncOptions {
    /** Clock. */
    now?: Date;
    /** CLEO home holding the global store and the state file. */
    cleoHome?: string;
    /** Runs the sync; defaults to `cloudSync`. */
    sync?: (projectRoot: string) => Promise<unknown>;
    /** Whether a store has a journal push/pull flag on; defaults to a read-only check. */
    syncEnabled?: (dbPath: string) => Promise<boolean>;
    /** Governor admission; `null` = deferred. */
    admit?: () => Promise<{
        release: () => Promise<void>;
    } | null>;
    /** Single-flight lock; throws when held. `onCompromised` fires if the lock is lost while held. */
    lock?: (onCompromised: (err: Error) => void) => Promise<{
        release: () => Promise<void>;
        abandon?: () => Promise<void>;
    }>;
    /** The unreleased flags; test seam. @defaultValue UNRELEASED_FLAGS */
    unreleasedFlags?: ReadonlySet<string>;
    /** Environment read by {@link autoSyncSuppressedBy}. @defaultValue process.env */
    env?: NodeJS.ProcessEnv;
}
/**
 * The test-runner or CI variable that suppresses every automatic sync: `VITEST` set,
 * `NODE_ENV=test`, or `CI` set to anything but empty, `0` or `false`. The one
 * predicate {@link autoCloudSync}, the command piggyback and `cleo cloud status`
 * read (T13602, T13606); an explicit `cleo cloud sync` is unaffected.
 *
 * @param env - The environment.
 * @returns `VITEST`, `NODE_ENV=test` or `CI`, or `null` when none applies.
 */
export declare function autoSyncSuppressedBy(env: NodeJS.ProcessEnv): string | null;
/**
 * Whether automatic sync may run: never while both `sync.push` and
 * `sync.pull` are unreleased (T13553; T13549 releases them).
 *
 * @param unreleased - The unreleased set. @defaultValue UNRELEASED_FLAGS
 * @returns True once either flag ships.
 */
export declare function autoSyncReleased(unreleased?: ReadonlySet<string>): boolean;
/**
 * The tick interval: `CLEO_AUTO_SYNC_INTERVAL_MIN` minutes, else
 * {@link AUTO_SYNC_INTERVAL_MS}. `0` turns the tick-driven sync off.
 *
 * @returns Milliseconds, or `null` when the tick sync is off.
 */
export declare function autoSyncIntervalMs(): number | null;
/**
 * Read the automatic sync state. Missing or malformed means empty.
 *
 * @param cleoHome - CLEO home. @defaultValue getCleoHome()
 * @returns The state.
 */
export declare function readAutoSyncState(cleoHome?: string): AutoSyncState;
/**
 * The `cleo cloud status` warning for a failed automatic sync: present while
 * the last failure is newer than the last success.
 *
 * @param cleoHome - CLEO home. @defaultValue getCleoHome()
 * @returns The warning, or `null`.
 */
export declare function autoSyncWarning(cleoHome?: string): CloudWarning | null;
/**
 * Run one automatic `cloud sync` of the project and global stores, if due.
 * Never throws.
 *
 * @param projectRoot - The project whose session ended or whose tick ran.
 * @param reason - What triggered it; a tick or command honours {@link autoSyncIntervalMs}.
 * @param opts - Test seams.
 * @returns What happened.
 * @task T13468
 */
export declare function autoCloudSync(projectRoot: string, reason: AutoSyncReason, opts?: AutoSyncOptions): Promise<AutoSyncOutcome>;
//# sourceMappingURL=auto-sync.d.ts.map