export declare const stateFilePath: (agentDir: string) => string;
export interface HintStore {
    /** Whether the hint still needs showing. Cached after the first read. */
    pending(): boolean;
    /** Record that the hint was shown. Returns false when persistence failed. */
    acknowledge(now?: string): boolean;
}
export interface HintStoreOptions {
    path: string;
    readFile?: (path: string) => string | null;
    writeFile?: (path: string, text: string) => void;
}
export declare function createHintStore({ path, readFile, writeFile, }: HintStoreOptions): HintStore;
/** A profile that was demoted because its model was unusable. */
export interface ProfileDemotion {
    profile: string;
    /** ISO-8601 timestamp of when the demotion was recorded. */
    at: string;
}
export interface ProfileStateStore {
    /** Returns the current demotion, or undefined if no demotion is active. */
    demotion(): ProfileDemotion | undefined;
    /**
     * Record that the given profile was chosen (demoting it for a retry window).
     * Returns false if the write failed.
     */
    record(profile: string, now?: Date): boolean;
    /**
     * Clear any demotion record without touching other keys in the state file.
     * Returns false if the write failed.
     */
    clear(): boolean;
}
export interface ProfileStateStoreOptions {
    path: string;
    readFile?: (path: string) => string | null;
    writeFile?: (path: string, text: string) => void;
}
export declare function createProfileStateStore({ path, readFile, writeFile, }: ProfileStateStoreOptions): ProfileStateStore;
/**
 * What the operator was last told about one project's Serena config, keyed by
 * the project root. The record is the nudge's whole memory: the state kind it
 * announced and the init-workspace revision that was current when it did.
 */
export interface SerenaReadinessRecord {
    /** The readiness kind announced (`missing`, `stale`, `outdated`, `ready`). */
    state: string;
    /** The bundled `init-workspace` revision in force at that moment. */
    revision: string;
    /** ISO-8601 timestamp of the announcement. */
    at: string;
}
export interface SerenaReadinessStore {
    /** The record for `projectKey`, or undefined when this project was never seen. */
    record(projectKey: string): SerenaReadinessRecord | undefined;
    /** Persist the record for `projectKey`. Returns false when the write failed. */
    latch(projectKey: string, record: SerenaReadinessRecord): boolean;
}
export interface SerenaReadinessStoreOptions {
    path: string;
    readFile?: (path: string) => string | null;
    writeFile?: (path: string, text: string) => void;
}
/**
 * The nudge's latch, in the package's own global state file beside the
 * first-run hint and the profile demotion — never inside the project, and never
 * inside any configuration. Read-merge-write throughout, so no other key in
 * that file is disturbed; every failure is soft (a latch that cannot be
 * persisted re-shows the nudge next session, which is a nuisance, not a fault).
 */
export declare function createSerenaReadinessStore({ path, readFile, writeFile, }: SerenaReadinessStoreOptions): SerenaReadinessStore;