/**
 * The host's largest memory users (T13914), so an admission wait names what
 * took the memory instead of waiting silently at a zero budget.
 *
 * macOS ranks by `top`'s MEM column, the process footprint: resident plus
 * compressed and swapped pages. `ps` RSS leaves those out, so a leaking
 * long-lived agent (17 GB, almost all compressed) reads as 260 MB there.
 * Linux ranks by `ps` RSS. Every failure reads as "no list", never an error.
 *
 * @task T13914
 */
import type { MemoryConsumer, MemoryPressureReading } from '@cleocode/contracts';
/** How many processes a wait names. */
export declare const TOP_MEMORY_COUNT = 3;
/** A probe younger than this is reused while the gate keeps refusing. */
export declare const TOP_MEMORY_REUSE_MS = 30000;
/** A FAILED probe is reused this long, so a hanging probe cannot block every pass. */
export declare const TOP_MEMORY_FAILED_REUSE_MS = 20000;
/** Forget that `top` failed (tests). */
export declare function _resetTopMemoryForTest(): void;
/** Runs one probe command and returns its stdout; throws on failure or timeout. */
export type ProbeRunner = (cmd: string, args: readonly string[]) => string;
/**
 * Parse `top -l 1 -o mem -stats pid,mem,command` output (macOS): the rows
 * after the `PID MEM COMMAND` header, MEM as `4391M`, `17G`, `512K` (a
 * trailing `+`/`-` is ignored).
 *
 * @param text - `top` stdout.
 * @param limit - Rows to keep.
 * @returns Largest first, as `top` sorted them.
 */
export declare function parseTopMemory(text: string, limit?: number): MemoryConsumer[];
/**
 * Parse `ps -eo pid=,rss=,comm=` output (RSS in KiB) and keep the largest.
 *
 * @param text - `ps` stdout.
 * @param limit - Rows to keep.
 * @returns Largest first.
 */
export declare function parsePsMemory(text: string, limit?: number): MemoryConsumer[];
/** Longest one probe may take; it is then SIGKILLed (T13964). */
export declare const TOP_MEMORY_TIMEOUT_MS = 2000;
/**
 * The host's largest memory users right now: one `top` sample on macOS
 * (footprint), falling back to `ps` RSS when `top` fails (and, once `top`
 * has failed on this host, going straight to `ps`); one `ps` on Linux. Each
 * probe is SIGKILLed after {@link TOP_MEMORY_TIMEOUT_MS}. `null` when no probe
 * could list them (the caller says UNKNOWN, never "nothing").
 *
 * @param limit - How many. @defaultValue {@link TOP_MEMORY_COUNT}
 * @param platform - @defaultValue process.platform
 * @param run - Runs one probe command (tests). @defaultValue a bounded execFileSync
 * @returns Largest first, or `null` when the probe failed.
 */
export declare function topMemoryConsumers(limit?: number, platform?: NodeJS.Platform, run?: ProbeRunner): MemoryConsumer[] | null;
/**
 * The memory gate's cause in words: the platform signals, then the largest
 * memory users when they were probed and how to free them, e.g.
 * `kernel level warn; swap 8.6 GiB used; largest memory users: agy pid 4242
 * 17.0 GiB, node pid 77 1.8 GiB (quit or restart them to free memory; check
 * with top -o mem)`.
 *
 * @param reading - The gate's readings.
 * @returns One line.
 */
export declare function memoryPressureCause(reading: MemoryPressureReading): string;
//# sourceMappingURL=top-memory.d.ts.map