export type FailureRecord = {
    ts: number;
    sessionId: string;
    task_summary: string;
    pattern: string;
    failed_action?: string;
    error_signature?: string;
    retries_before_giveup?: number;
};
/**
 * Append a single failure record. Rolling-rotates the log if it exceeds the
 * size cap. Best-effort — never throws.
 */
export declare function logFailure(record: FailureRecord): void;
/**
 * Read all logged failures. Used by the curator. Returns an empty array on
 * any read error.
 */
export declare function readFailures(): Promise<FailureRecord[]>;
type FailureCluster = {
    pattern: string;
    count: number;
    sample_tasks: string[];
    sample_errors: string[];
    first_seen_ms: number;
    last_seen_ms: number;
};
/**
 * Group failures by `pattern`. Patterns are author-supplied labels so they
 * can be coarse ("klaw-cli-not-found") or fine ("missing-pty-flag-on-pnpm").
 * Returns clusters with ≥ MIN_OCCURRENCES occurrences, sorted by count desc.
 */
export declare function clusterFailures(records: FailureRecord[]): FailureCluster[];
/** Persist the latest cluster snapshot for downstream consumers. */
export declare function saveFailureClusters(clusters: FailureCluster[]): Promise<void>;
/**
 * Heuristic: derive a stable pattern label from a tool name and error text.
 * Used by call sites that don't have a curated label of their own. Keeps
 * common cases collapsed without a model call.
 */
export declare function derivePatternLabel(params: {
    toolName?: string;
    errorText?: string;
}): string | null;
export {};