/**
 * Piggyback sync on normal CLI commands (T13553): a command in a linked
 * project starts a detached `autoCloudSync(projectRoot, 'command')` child at
 * most once per {@link autoSyncIntervalMs}, the way the presence refresh
 * piggybacks (T13289). No daemon, timer or server; the foreground command
 * never waits for the child.
 *
 * The check on the command's path is one `stat` of a per-project stamp under
 * the CLEO home, so one busy project cannot starve another's sync (T13556).
 * The stamp is written before the spawn, so a failing child is retried a
 * window later, not on every command. Everything else (the config opt-out
 * `cloud.autoSync`, flags, login, the network) runs in the child, where
 * `autoCloudSync` adds its own throttle and the cross-process lock that keeps
 * this, session end and the sentient tick from syncing twice.
 *
 * Never spawned for heavy or evidence runs (`CLEO_RUN_CLASS` is set in every
 * governed child), for `cleo run` / `cleo verify` / `cleo cloud`, under a
 * test runner or CI (`VITEST`, `NODE_ENV=test`, `CI`: a linked fixture must
 * never start detached syncs that load the machine), or when
 * `CLEO_DISABLE_AUTO_SYNC=1` or `CLEO_AUTO_SYNC_INTERVAL_MIN=0`.
 *
 * @task T13553
 */
import type { CloudWarning } from '@cleocode/contracts';
import { type AutoSyncOutcome } from './auto-sync.js';
/** Environment switch that turns the command piggyback off (`1`). */
export declare const AUTO_SYNC_DISABLE_ENV = "CLEO_DISABLE_AUTO_SYNC";
/** The `cleo cloud status` warning code while a test runner or CI suppresses auto-sync (T13602). */
export declare const W_AUTO_SYNC_SUPPRESSED = "W_AUTO_SYNC_SUPPRESSED";
/**
 * The `cleo cloud status` warning while a test runner or CI suppresses the
 * background sync. Absent while sync is unreleased: nothing would run anyway.
 *
 * @param env - The environment. @defaultValue process.env
 * @param unreleasedFlags - The unreleased flags; test seam. @defaultValue UNRELEASED_FLAGS
 * @returns The warning naming the variable, or `null`.
 */
export declare function autoSyncSuppressedWarning(env?: NodeJS.ProcessEnv, unreleasedFlags?: ReadonlySet<string>): CloudWarning | null;
/** How {@link startCommandAutoSync} ended. */
export type CommandAutoSyncOutcome = 'disabled' | 'skipped' | 'throttled' | 'spawned' | 'failed';
/** Options for {@link startCommandAutoSync}. */
export interface CommandAutoSyncOptions {
    /** The linked project root. */
    projectRoot: string;
    /** The command's root verb (`show`, `add`, …), if any. */
    verb?: string;
    /** Environment. @defaultValue process.env */
    env?: NodeJS.ProcessEnv;
    /** CLEO home holding the stamp. @defaultValue getCleoHome() */
    cleoHome?: string;
    /** Clock. */
    now?: () => Date;
    /** Starts the detached child; defaults to spawning the worker entry. */
    spawnWorker?: (projectRoot: string) => void;
    /** The unreleased flags; test seam. @defaultValue UNRELEASED_FLAGS */
    unreleasedFlags?: ReadonlySet<string>;
}
/**
 * The command's root verb: the first argv token naming a root command, so the
 * value of a leading global option (`cleo --cwd x run`) is never taken for it.
 *
 * @param argv - The command's argv after the executable and script.
 * @param commands - The root commands, keyed by name and alias.
 * @returns The root verb, or `undefined` when no token names a root command.
 */
export declare function commandRootVerb(argv: readonly string[], commands: Readonly<Record<string, unknown>>): string | undefined;
/**
 * Start a background sync for this linked project if the window has elapsed.
 * Never throws and never waits for the sync.
 *
 * @param opts - Project root, verb and test seams.
 * @returns What happened on the command's path.
 */
export declare function startCommandAutoSync(opts: CommandAutoSyncOptions): CommandAutoSyncOutcome;
/**
 * The detached child's body: honour the config opt-out `cloud.autoSync:
 * false` (project, then global), then {@link autoCloudSync} with reason
 * `command`. Never throws.
 *
 * @param projectRoot - The linked project root.
 * @param seams - Test seams.
 * @returns The sync outcome, or `disabled` when the config turns it off.
 */
export declare function runCommandAutoSync(projectRoot: string, seams?: {
    readConfig?: (projectRoot: string) => Promise<boolean | undefined>;
    sync?: (projectRoot: string) => Promise<AutoSyncOutcome>;
}): Promise<AutoSyncOutcome>;
//# sourceMappingURL=auto-sync-command.d.ts.map