/** Which process-level fault produced a record. */
export type CrashKind = 'uncaughtException' | 'unhandledRejection';
/** Filename of the crash log within a surface's home-anchored root. */
export declare const CRASH_LOG_FILENAME = "crashes.jsonl";
/**
 * Count cap on retained crash records. Small on purpose: the newest crashes
 * are the ones under investigation, and this file is read by a human, not a
 * query engine. Age and total-size caps come from the retention registry on
 * top of this.
 */
export declare const CRASH_LOG_MAX_RECORDS = 25;
/**
 * Cap on a single record's stack text. A runaway recursive stack can be
 * megabytes; truncating keeps one pathological crash from consuming the whole
 * store's size budget and evicting the history around it.
 */
export declare const CRASH_STACK_MAX_CHARS = 8000;
/** One captured process-level fault. */
export interface CrashRecord {
    /** ISO-8601 UTC timestamp of the fault. */
    readonly timestamp: string;
    /** Which process-level fault fired. */
    readonly kind: CrashKind;
    /** The error's message, or a stringified non-Error throw value. */
    readonly message: string;
    /** The stack, truncated to {@link CRASH_STACK_MAX_CHARS}; null when absent. */
    readonly stack: string | null;
    /** Surface version the fault happened on. */
    readonly version: string;
    /** Process id that faulted. */
    readonly pid: number;
    /** Session active at the moment of the fault; null when none was active. */
    readonly sessionId: string | null;
    /** Surface that faulted, e.g. `'agent'`. */
    readonly surface: string;
}
/** Inputs for {@link buildCrashRecord} other than the thrown value itself. */
export interface CrashContext {
    readonly version: string;
    readonly surface: string;
    readonly sessionId: string | null;
    readonly pid?: number;
    /** Injectable clock for deterministic tests. */
    readonly now?: () => Date;
}
/**
 * Build a crash record from a thrown value. Never throws: a crash handler that
 * itself throws loses the very report it exists to produce, so every field
 * extraction is defensive against exotic throw values (a Proxy whose `message`
 * getter throws, a null prototype object, a bare string).
 */
export declare function buildCrashRecord(kind: CrashKind, thrown: unknown, context: CrashContext): CrashRecord;
/**
 * Read every well-formed record from a crash log, oldest first.
 *
 * Content-validated, never existence-validated: a line that does not parse or
 * does not carry the record shape is skipped, so one torn tail line (the
 * normal outcome of crashing mid-write) still yields every record before it.
 * A missing or unreadable file reads as an empty history.
 */
export declare function readCrashRecords(filePath: string): CrashRecord[];
/**
 * Append one crash record, enforcing the count cap.
 *
 * Fast path is a plain O_APPEND write, a single small line, which is the
 * cheapest thing that can land from a dying process. The rewrite that enforces
 * {@link CRASH_LOG_MAX_RECORDS} only runs once the file has actually grown
 * past the cap, and goes through `writeFileAtomic` so a crash during the
 * trim cannot leave a truncated log.
 *
 * Best-effort by contract: returns `false` instead of throwing when the write
 * fails. The caller is an exit-boundary handler whose remaining duty (stderr,
 * activity log, exit code) must still run on a read-only or full disk.
 */
export declare function appendCrashRecord(filePath: string, record: CrashRecord): boolean;
//# sourceMappingURL=crash-capture.d.ts.map