import type { Database } from "../../../shared/sqlite";
export interface DreamQueueEntry {
    id: number;
    /** Project identity (e.g. "git:<sha>"), NOT a filesystem path */
    projectIdentity: string;
    reason: string;
    enqueuedAt: number;
    startedAt: number | null;
}
export declare function ensureDreamQueueTable(db: Database): void;
export declare function hasActiveDreamLease(db: Database): boolean;
/** Enqueue a project for dreaming. Skips if the same project already has any queue entry (queued or running).
 *
 * @param force - When true (e.g. manual /ctx-dream), uses the lease TTL (2 min) as the stale threshold
 *   instead of the full 2-hour max-runtime window. This lets users re-trigger dreaming after a crash or
 *   restart even when the previous queue entry was started only seconds ago.
 */
export declare function enqueueDream(db: Database, projectIdentity: string, reason: string, force?: boolean): DreamQueueEntry | null;
/** Peek at the next unstarted entry without claiming it.
 *
 * @param projectIdentity - When provided, only matches entries for this project.
 *   This is critical for cross-process coexistence: each running OpenCode/Pi
 *   process registers exactly one project, so it must only drain entries that
 *   belong to it. Without this filter, Pi (running in project A) would dequeue
 *   queue entries for project B and try to dream B with Pi's runner — which
 *   either spawns `pi` in a directory that doesn't exist (the `git:<sha>`
 *   identity string) or, even if it succeeded, runs the wrong harness for that
 *   project.
 */
export declare function peekQueue(db: Database, projectIdentity?: string): DreamQueueEntry | null;
/** Claim the next unstarted entry atomically by marking started_at. Returns null if queue is empty.
 *
 * @param projectIdentity - When provided, only dequeues entries for this project.
 *   See `peekQueue` for the cross-process coexistence rationale.
 */
export declare function dequeueNext(db: Database, projectIdentity?: string): DreamQueueEntry | null;
/** Remove a completed or failed entry from the queue. */
export declare function removeDreamEntry(db: Database, id: number): void;
/** Reset a dequeued entry so it can be retried (e.g., after lease failure). Increments retry_count. */
export declare function resetDreamEntry(db: Database, id: number): void;
/** Get the retry count for a queue entry. */
export declare function getEntryRetryCount(db: Database, id: number): number;
/**
 * Clear stale started entries (stuck for more than maxAgeMs).
 *
 * Callers MUST gate this on `!hasActiveDreamLease(db)` — a healthy long-running
 * dream can exceed `maxAgeMs` while still renewing its lease, and deleting its
 * own row mid-run is the bug this guard prevents (mirrors the enqueue path).
 *
 * `projectIdentity` scopes the delete to one project. The shared `dream_queue`
 * is cross-process (OpenCode + Pi); a global delete would reap other hosts'
 * still-running rows. Omit only for the legacy "reap any" test path.
 */
export declare function clearStaleEntries(db: Database, maxAgeMs: number, projectIdentity?: string): number;
//# sourceMappingURL=queue.d.ts.map