export type LockState = {
    path: string;
    held: boolean;
    reason?: string;
    startedAt: number;
    /** mtime of the last-run sidecar before this run took the lock; failLock restores it. */
    priorStampMtime?: number;
    /** Random identity written into the lock file; cleanup only removes the lock it wrote. */
    token?: string;
};
/**
 * The scheduler's last-run timestamp lives in a sidecar beside the lock, never in the
 * lock file itself: acquiring, releasing or cleaning up the lock touches only the PID
 * marker, so lock lifecycle does not destroy the timestamp the time gate reads.
 */
export declare function lastRunPath(lockPath: string): string;
/**
 * Acquire the dream lock with Git-style exclusive existence locking: one O_CREAT|O_EXCL
 * creation. An existing path refuses acquisition regardless of its contents, PID, or age,
 * and is never read for permission, replaced, or removed. There is no automatic stale
 * recovery; a crash-left lock is human cleanup after confirming no dream is running.
 */
export declare function acquireLock(path: string): LockState;
/** Release only the lock this run acquired. Idempotent: repeated cleanup does nothing. */
export declare function releaseLock(lock: LockState): void;
/**
 * A failed run must not advance the scheduler: restore the previous timestamp, or remove
 * the one this run wrote when there was none. Only this run's own marker is removed, and
 * the state is marked released so a later cleanup attempt is harmless.
 */
export declare function failLock(lock: LockState): void;