@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/native-metrics/cgroup-memory.d.ts

@@ -1,193 +1,240 @@
-import { ContainerMemorySnapshot, IScopedLogger } from '@camstack/types';
 /**
- * Which hierarchy answered. Reported so a reading is never ambiguous.
- *
- * Narrowed from {@link ContainerMemorySnapshot}'s own field rather than
- * re-declared: the shape is the capability's Zod schema and this file must not
- * own a second copy of it.
- */
-export type CgroupMemorySource = ContainerMemorySnapshot['source'];
+* The container's own memory, read from the cgroup — the number no sum of
+* per-process RSS can ever produce.
+*
+* ## Why this file exists
+*
+* Every memory number camstack had before it was PER PROCESS: the `[mem]`
+* heartbeat per runner (`packages/system/src/kernel/heap-watch.ts`) and the
+* `ps`-derived `memoryRssBytes` on each `NodeProcess`. On 2026-08-29 the hub's
+* 39 processes summed to 15.81 GiB while the container reported 23.14 GiB, and
+* the missing ~7 GiB was read for a leak. It was not one. `memory.stat` settled
+* it in a single command:
+*
+* ```
+* anon 19946409984   file 3642105856   shmem 1860067328   slab 95465928
+* memory.current 24045301760   memory.max 34359738368
+* ```
+*
+* **The sum of per-process RSS can never equal the container total.** Page
+* cache (`file`), shared memory (`shmem`, which is where the i915 driver parks
+* GPU buffers) and kernel slab belong to the cgroup, not to any process in the
+* way `ps` counts. On this hub they are ~6 GiB of 23. Read once by hand they
+* say nothing about direction; that is what this file is for.
+*
+* ## What it is NOT
+*
+* Measurement only. Nothing here reclaims, trims, drops caches or tunes an
+* allocator. The operator's standing position is that memory ceilings and
+* `malloc` variables are patches over deeper problems
+* (`docs/design/plans/2026-08-29-remove-the-memory-ceilings.md`); this exists
+* to make the deeper problem visible, never to paper over it.
+*
+* ## Absent is ABSENT
+*
+* Every unavailable number is `null`, never `0`. A node with no cgroup (a
+* developer Mac, a bare-metal host, a container with the hierarchy hidden)
+* produces `null` from {@link ContainerMemoryProbe.sample} and contributes no
+* point at all — because a zero here is indistinguishable from a healthy
+* container that happens to use no memory, which is the exact class of lie
+* this repo has been bitten by.
+*
+* ## The reads are pure, the I/O is injected
+*
+* Every parse below is a pure function over text, so the shapes are testable
+* against real `memory.stat` fixtures without a Linux kernel. The only impure
+* surface is {@link CgroupFileReader}, one method wide.
+*/
+import type { ContainerMemorySnapshot, IScopedLogger } from "@camstack/types";
+/**
+* Which hierarchy answered. Reported so a reading is never ambiguous.
+*
+* Narrowed from {@link ContainerMemorySnapshot}'s own field rather than
+* re-declared: the shape is the capability's Zod schema and this file must not
+* own a second copy of it.
+*/
+export type CgroupMemorySource = ContainerMemorySnapshot["source"];
 /** The one impure surface. Returns `null` for anything unreadable. */
 export interface CgroupFileReader {
-    read(path: string): string | null;
+	read(path: string): string | null;
 }
 /** `readFileSync`, with every failure flattened to `null`. */
 export declare const nodeCgroupFileReader: CgroupFileReader;
 /** Where the v2 unified hierarchy is mounted, and where v1 hangs its controllers. */
 export declare const CGROUP_MOUNT_ROOT = "/sys/fs/cgroup";
 /**
- * The i915 GEM accounting file.
- *
- * **debugfs, and it is not mounted in our containers.** Verified on the live
- * hub on 2026-08-29: readable on the Unraid host (`6014 shrinkable [0 free]
- * objects, 1194934272 bytes`), `ENOENT` inside the `CamStack` container where
- * `native-metrics` actually runs. It is probed ONCE per process and latched —
- * a bind mount cannot appear under a running container — so an absent file
- * costs one failed `open` for the life of the runner and one log line, never a
- * failure per tick.
- *
- * Making it populate is a one-line change on the container, not here:
- * mounting `/sys/kernel/debug` read-only into `CamStack` fills this field on
- * the next sample with no code change.
- */
+* The i915 GEM accounting file.
+*
+* **debugfs, and it is not mounted in our containers.** Verified on the live
+* hub on 2026-08-29: readable on the Unraid host (`6014 shrinkable [0 free]
+* objects, 1194934272 bytes`), `ENOENT` inside the `CamStack` container where
+* `native-metrics` actually runs. It is probed ONCE per process and latched —
+* a bind mount cannot appear under a running container — so an absent file
+* costs one failed `open` for the life of the runner and one log line, never a
+* failure per tick.
+*
+* Making it populate is a one-line change on the container, not here:
+* mounting `/sys/kernel/debug` read-only into `CamStack` fills this field on
+* the next sample with no code change.
+*/
 export declare const I915_GEM_OBJECTS_PATH = "/sys/kernel/debug/dri/0/i915_gem_objects";
 /** Where the numbers for one hierarchy live, once resolved. */
 export interface CgroupMemoryLayout {
-    readonly source: CgroupMemorySource;
-    /** Directory the three files below sit in. Kept for the resolution log line. */
-    readonly directory: string;
-    readonly currentPath: string;
-    readonly limitPath: string;
-    readonly statPath: string;
+	readonly source: CgroupMemorySource;
+	/** Directory the three files below sit in. Kept for the resolution log line. */
+	readonly directory: string;
+	readonly currentPath: string;
+	readonly limitPath: string;
+	readonly statPath: string;
 }
 /** What `/proc/self/cgroup` says about this process. */
 export interface CgroupSelfEntry {
-    readonly version: 'v2' | 'v1';
-    /** Path RELATIVE to the hierarchy root, always leading-slashed. */
-    readonly path: string;
+	readonly version: "v2" | "v1";
+	/** Path RELATIVE to the hierarchy root, always leading-slashed. */
+	readonly path: string;
 }
 /**
- * Parse `/proc/self/cgroup`.
- *
- * Two formats, and the file may contain both on a hybrid host:
- *
- * ```
- * 0::/                                  ← v2 unified
- * 5:memory:/docker/9f3c…                ← v1, memory controller
- * 4:cpu,cpuacct:/docker/9f3c…           ← v1, other controllers
- * ```
- *
- * v2 wins when present: on a hybrid host the unified hierarchy is the one
- * carrying `memory.current`, and every camstack deployment is v2 (verified on
- * the live hub, which reports the single line `0::/`).
- *
- * Returns `null` when the file names no memory hierarchy at all — which is
- * also what a non-Linux host produces, because there is no file to read.
- */
+* Parse `/proc/self/cgroup`.
+*
+* Two formats, and the file may contain both on a hybrid host:
+*
+* ```
+* 0::/                                  ← v2 unified
+* 5:memory:/docker/9f3c…                ← v1, memory controller
+* 4:cpu,cpuacct:/docker/9f3c…           ← v1, other controllers
+* ```
+*
+* v2 wins when present: on a hybrid host the unified hierarchy is the one
+* carrying `memory.current`, and every camstack deployment is v2 (verified on
+* the live hub, which reports the single line `0::/`).
+*
+* Returns `null` when the file names no memory hierarchy at all — which is
+* also what a non-Linux host produces, because there is no file to read.
+*/
 export declare function parseCgroupSelf(text: string): CgroupSelfEntry | null;
 /**
- * Parse a `memory.stat` file — v1 or v2, both are `key value` per line.
- *
- * Unknown keys are KEPT rather than refused: a v2 `memory.stat` carries ~50
- * fields and we read five of them, and a kernel that adds a sixth must not
- * turn into a parse failure. A malformed line is skipped, not thrown on.
- */
+* Parse a `memory.stat` file — v1 or v2, both are `key value` per line.
+*
+* Unknown keys are KEPT rather than refused: a v2 `memory.stat` carries ~50
+* fields and we read five of them, and a kernel that adds a sixth must not
+* turn into a parse failure. A malformed line is skipped, not thrown on.
+*/
 export declare function parseCgroupStat(text: string): ReadonlyMap<string, number>;
 /**
- * Parse a single-scalar cgroup file (`memory.current`, `memory.max`, …).
- *
- * `max` — v2's word for "no limit" — and v1's `V1_UNLIMITED_SENTINEL` both
- * become `null`, because a ceiling nothing can reach is not a ceiling and
- * charting it as 8 exabytes would flatten every real series to zero.
- */
+* Parse a single-scalar cgroup file (`memory.current`, `memory.max`, …).
+*
+* `max` — v2's word for "no limit" — and v1's `V1_UNLIMITED_SENTINEL` both
+* become `null`, because a ceiling nothing can reach is not a ceiling and
+* charting it as 8 exabytes would flatten every real series to zero.
+*/
 export declare function parseCgroupScalar(text: string): number | null;
 /**
- * Parse the first line of `i915_gem_objects`.
- *
- * ```
- * 6014 shrinkable [0 free] objects, 1194934272 bytes
- * ```
- *
- * Only the byte total is taken. The format has changed across kernel releases
- * more than once, so a line that does not match reads `null` — an unrecognised
- * format is UNKNOWN, never zero.
- */
+* Parse the first line of `i915_gem_objects`.
+*
+* ```
+* 6014 shrinkable [0 free] objects, 1194934272 bytes
+* ```
+*
+* Only the byte total is taken. The format has changed across kernel releases
+* more than once, so a line that does not match reads `null` — an unrecognised
+* format is UNKNOWN, never zero.
+*/
 export declare function parseI915GemObjects(text: string): number | null;
 /**
- * Find the cgroup from INSIDE this process — never a hard-coded path.
- *
- * The path the hub happens to have (`/sys/fs/cgroup/docker/<id>/memory.stat`
- * as seen from the Unraid host) is an artefact of where you are standing. From
- * inside the container the same cgroup is at the mount ROOT, because Docker
- * gives the container its own cgroup namespace and `/proc/self/cgroup` reports
- * `0::/`. Hard-coding either one breaks the other.
- *
- * So the resolution is: ask `/proc/self/cgroup` which hierarchy and which
- * path, then take the FIRST candidate directory that actually publishes the
- * usage file.
- *
- * - **v2** — `<mount><path>` then `<mount>`. The second candidate is the
- *   namespaced case and the one that answers on our hub; the first is the
- *   un-namespaced case (a host process, or `--cgroupns=host`).
- * - **v1** — `<mount>/memory<path>` then `<mount>/memory`, same reasoning.
- * - **neither** — `null`. macOS has no `/proc/self/cgroup` at all, so a
- *   developer Mac lands here and reports nothing, which is the truth.
- */
+* Find the cgroup from INSIDE this process — never a hard-coded path.
+*
+* The path the hub happens to have (`/sys/fs/cgroup/docker/<id>/memory.stat`
+* as seen from the Unraid host) is an artefact of where you are standing. From
+* inside the container the same cgroup is at the mount ROOT, because Docker
+* gives the container its own cgroup namespace and `/proc/self/cgroup` reports
+* `0::/`. Hard-coding either one breaks the other.
+*
+* So the resolution is: ask `/proc/self/cgroup` which hierarchy and which
+* path, then take the FIRST candidate directory that actually publishes the
+* usage file.
+*
+* - **v2** — `<mount><path>` then `<mount>`. The second candidate is the
+*   namespaced case and the one that answers on our hub; the first is the
+*   un-namespaced case (a host process, or `--cgroupns=host`).
+* - **v1** — `<mount>/memory<path>` then `<mount>/memory`, same reasoning.
+* - **neither** — `null`. macOS has no `/proc/self/cgroup` at all, so a
+*   developer Mac lands here and reports nothing, which is the truth.
+*/
 export declare function resolveCgroupMemoryLayout(fs: CgroupFileReader): CgroupMemoryLayout | null;
 /**
- * Turn one layout's three files into a snapshot.
- *
- * Pure over the text, so the whole mapping — including a v2 `memory.stat` full
- * of fields we do not read — is testable against a real fixture.
- *
- * v1's `memory.stat` names the same quantities differently and publishes fewer
- * of them: `rss` is the anonymous charge, `cache` is the page cache, and there
- * is no slab accounting at all. Mapping them onto the same field names is what
- * makes a v1 node and a v2 node comparable; reporting `slabBytes: null` on v1
- * is what stops that comparison from lying.
- */
+* Turn one layout's three files into a snapshot.
+*
+* Pure over the text, so the whole mapping — including a v2 `memory.stat` full
+* of fields we do not read — is testable against a real fixture.
+*
+* v1's `memory.stat` names the same quantities differently and publishes fewer
+* of them: `rss` is the anonymous charge, `cache` is the page cache, and there
+* is no slab accounting at all. Mapping them onto the same field names is what
+* makes a v1 node and a v2 node comparable; reporting `slabBytes: null` on v1
+* is what stops that comparison from lying.
+*/
 export declare function buildContainerMemorySnapshot(input: {
-    readonly source: CgroupMemorySource;
-    readonly currentText: string;
-    readonly limitText: string | null;
-    readonly statText: string | null;
-    readonly gpuShmemBytes: number | null;
+	readonly source: CgroupMemorySource;
+	readonly currentText: string;
+	readonly limitText: string | null;
+	readonly statText: string | null;
+	readonly gpuShmemBytes: number | null;
 }): ContainerMemorySnapshot | null;
 export interface ContainerMemoryProbeDeps {
-    readonly logger: IScopedLogger;
-    readonly fs?: CgroupFileReader;
-    /** Set `false` to skip the debugfs probe entirely. Default `true`. */
-    readonly readGpu?: boolean;
+	readonly logger: IScopedLogger;
+	readonly fs?: CgroupFileReader;
+	/** Set `false` to skip the debugfs probe entirely. Default `true`. */
+	readonly readGpu?: boolean;
 }
 /**
- * The sampler. Resolves once, latches, and logs TRANSITIONS only.
- *
- * Three states are worth a line and none of them is worth one per tick:
- *
- * 1. **Resolution** — once, at the first sample. Either the layout that
- *    answered, or "no cgroup on this node", which is a fact about the node and
- *    not an error.
- * 2. **GPU probe** — once, at the first sample. Absent debugfs is the normal
- *    case inside a container and is stated as such, then never retried: a bind
- *    mount cannot appear under a running container.
- * 3. **Read failing / recovering** — a cgroup that resolved and then stopped
- *    answering is a real change and says so, once in each direction. A tick
- *    that fails while already failing is silent, because the first line
- *    already said it.
- *
- * The silence is bounded by design: at the 10 s snapshot cadence a per-tick
- * warning would be 8 640 lines a day on a node that simply is not Linux.
- */
+* The sampler. Resolves once, latches, and logs TRANSITIONS only.
+*
+* Three states are worth a line and none of them is worth one per tick:
+*
+* 1. **Resolution** — once, at the first sample. Either the layout that
+*    answered, or "no cgroup on this node", which is a fact about the node and
+*    not an error.
+* 2. **GPU probe** — once, at the first sample. Absent debugfs is the normal
+*    case inside a container and is stated as such, then never retried: a bind
+*    mount cannot appear under a running container.
+* 3. **Read failing / recovering** — a cgroup that resolved and then stopped
+*    answering is a real change and says so, once in each direction. A tick
+*    that fails while already failing is silent, because the first line
+*    already said it.
+*
+* The silence is bounded by design: at the 10 s snapshot cadence a per-tick
+* warning would be 8 640 lines a day on a node that simply is not Linux.
+*/
 export declare class ContainerMemoryProbe {
-    private readonly logger;
-    private readonly fs;
-    private readonly wantGpu;
-    private resolved;
-    private layout;
-    private gpuProbed;
-    private gpuReadable;
-    /** `null` until the first sample — so the FIRST outcome is a transition too. */
-    private lastReadOk;
-    constructor(deps: ContainerMemoryProbeDeps);
-    /** Did this node resolve a cgroup at all? Absent is a reportable fact. */
-    get available(): boolean;
-    /**
-     * One reading, or `null` when this node has no cgroup or the cgroup stopped
-     * answering. `null` is ABSENT — the caller contributes no point, and no
-     * point is what a chart must show, never a zero.
-     */
-    sample(): ContainerMemorySnapshot | null;
-    /** Resolve on first use and never again — a cgroup does not move under a pid. */
-    private resolveOnce;
-    /**
-     * The GPU number, probed once.
-     *
-     * It is host-wide and lives in debugfs, so it is absent far more often than
-     * it is present — inside every camstack container today. One `open` decides
-     * it for the life of the process; after that an unreadable file costs
-     * nothing at all, not even a syscall.
-     */
-    private readGpuShmem;
-    /** Log a read outcome only when it CHANGES. Never once per tick. */
-    private noteRead;
+	private readonly logger;
+	private readonly fs;
+	private readonly wantGpu;
+	private resolved;
+	private layout;
+	private gpuProbed;
+	private gpuReadable;
+	/** `null` until the first sample — so the FIRST outcome is a transition too. */
+	private lastReadOk;
+	constructor(deps: ContainerMemoryProbeDeps);
+	/** Did this node resolve a cgroup at all? Absent is a reportable fact. */
+	get available(): boolean;
+	/**
+	* One reading, or `null` when this node has no cgroup or the cgroup stopped
+	* answering. `null` is ABSENT — the caller contributes no point, and no
+	* point is what a chart must show, never a zero.
+	*/
+	sample(): ContainerMemorySnapshot | null;
+	/** Resolve on first use and never again — a cgroup does not move under a pid. */
+	private resolveOnce;
+	/**
+	* The GPU number, probed once.
+	*
+	* It is host-wide and lives in debugfs, so it is absent far more often than
+	* it is present — inside every camstack container today. One `open` decides
+	* it for the life of the process; after that an unreadable file costs
+	* nothing at all, not even a syscall.
+	*/
+	private readGpuShmem;
+	/** Log a read outcome only when it CHANGES. Never once per tick. */
+	private noteRead;
 }

package/dist/builtins/native-metrics/cgroup-pids.d.ts

@@ -1,112 +1,159 @@
-import { IScopedLogger } from '@camstack/types';
-import { CgroupFileReader } from './cgroup-memory.js';
+/**
+* The container's pid ceiling — the limit that stops work without an error
+* anyone reads.
+*
+* ## Why this file exists
+*
+* A container cgroup counts **THREADS**, not processes. This hub runs with
+* `pids.max` 2048 and was measured refusing 22 `clone()` calls in 45 minutes.
+* A refused clone is not an exception that travels: an ffmpeg child that
+* cannot start its decode threads runs degraded or dies, a worker pool comes
+* up short, a spawn fails — and what the operator SEES is media that stopped.
+* Nothing in the product read the counter, so the only trace of the ceiling
+* was the damage it did.
+*
+* Live hub, 2026-09-18, verbatim:
+*
+* ```
+* /sys/fs/cgroup/pids.current → 973
+* /sys/fs/cgroup/pids.max     → 2048
+* /sys/fs/cgroup/pids.events  → max 0
+* ```
+*
+* ## `pids.events` is the proof, `pids.current` is only the weather
+*
+* `pids.current` says how close we are. `pids.events`' `max` counter says how
+* many times the kernel ALREADY said no — it is monotonic for the life of the
+* cgroup, so a rise between two samples is a refusal that happened in that
+* window, and nothing else can produce it. That is the difference between "it
+* looks tight" and "we lost work", and only the second one is worth waking
+* someone for.
+*
+* ## What it is NOT
+*
+* Measurement only. Nothing here raises a limit, kills a process or trims a
+* pool. The ceiling is the operator's (`--pids-limit` on the container) and
+* the thread counts are the subsystems' own; this file exists so that both are
+* decided on a number instead of a hunch.
+*
+* ## Absent is ABSENT
+*
+* A node with no cgroup — a developer Mac, a bare-metal host — produces
+* `null`, never zero, exactly as {@link ContainerMemoryProbe} does. `max` of
+* `max` (no ceiling) is `null` too: a fraction of no ceiling is not 0 %.
+*
+* The parsing is pure and the I/O is the same injected {@link CgroupFileReader}
+* the memory probe uses, so every shape here is testable against real files.
+*/
+import type { IScopedLogger } from "@camstack/types";
+import type { CgroupFileReader } from "./cgroup-memory.js";
 /** Which hierarchy answered — reported so a reading is never ambiguous. */
-export type CgroupPidsSource = 'cgroup-v2' | 'cgroup-v1';
+export type CgroupPidsSource = "cgroup-v2" | "cgroup-v1";
 /** One reading of the ceiling and our distance from it. */
 export interface ContainerPidsSnapshot {
-    readonly source: CgroupPidsSource;
-    /** Threads (not processes) charged to this cgroup right now. */
-    readonly current: number;
-    /** The ceiling, or `null` when there is none. */
-    readonly max: number | null;
-    /** `current / max`, or `null` without a ceiling. */
-    readonly usedFraction: number | null;
-    /** Lifetime count of REFUSED forks, or `null` when the kernel does not say. */
-    readonly refusals: number | null;
+	readonly source: CgroupPidsSource;
+	/** Threads (not processes) charged to this cgroup right now. */
+	readonly current: number;
+	/** The ceiling, or `null` when there is none. */
+	readonly max: number | null;
+	/** `current / max`, or `null` without a ceiling. */
+	readonly usedFraction: number | null;
+	/** Lifetime count of REFUSED forks, or `null` when the kernel does not say. */
+	readonly refusals: number | null;
 }
 /** Where the files for one hierarchy live, once resolved. */
 export interface CgroupPidsLayout {
-    readonly source: CgroupPidsSource;
-    readonly directory: string;
-    readonly currentPath: string;
-    readonly maxPath: string;
-    readonly eventsPath: string;
+	readonly source: CgroupPidsSource;
+	readonly directory: string;
+	readonly currentPath: string;
+	readonly maxPath: string;
+	readonly eventsPath: string;
 }
 /**
- * `pids.max` is either a number or the word `max`.
- *
- * `max` means NO ceiling, and that is `null` — not `Infinity`, not a huge
- * number. A ceiling nothing can reach is not a ceiling, and reporting one
- * would make every utilisation fraction on an unlimited node read as 0 %.
- */
+* `pids.max` is either a number or the word `max`.
+*
+* `max` means NO ceiling, and that is `null` — not `Infinity`, not a huge
+* number. A ceiling nothing can reach is not a ceiling, and reporting one
+* would make every utilisation fraction on an unlimited node read as 0 %.
+*/
 export declare function parsePidsMax(text: string): number | null;
 /**
- * `pids.events` is `key value` per line; we read exactly one key:
- *
- * ```
- * max 22
- * ```
- *
- * `max` is the number of times a fork was refused because the limit was hit.
- * A kernel that publishes only `pids.events.local`, or a file we cannot make
- * sense of, answers `null` — unknown, never zero, because zero here means "no
- * refusals have ever happened" and that is a claim.
- */
+* `pids.events` is `key value` per line; we read exactly one key:
+*
+* ```
+* max 22
+* ```
+*
+* `max` is the number of times a fork was refused because the limit was hit.
+* A kernel that publishes only `pids.events.local`, or a file we cannot make
+* sense of, answers `null` — unknown, never zero, because zero here means "no
+* refusals have ever happened" and that is a claim.
+*/
 export declare function parsePidsEvents(text: string): number | null;
 /** Turn one layout's files into a snapshot. Pure over the text. */
 export declare function buildContainerPidsSnapshot(input: {
-    readonly source: CgroupPidsSource;
-    readonly currentText: string;
-    readonly maxText: string | null;
-    readonly eventsText: string | null;
+	readonly source: CgroupPidsSource;
+	readonly currentText: string;
+	readonly maxText: string | null;
+	readonly eventsText: string | null;
 }): ContainerPidsSnapshot | null;
 /**
- * Find the pids cgroup from INSIDE this process, never a hard-coded path —
- * same reasoning as the memory layout: from inside the container the cgroup is
- * at the mount ROOT (`0::/`), from the host it is `<mount>/docker/<id>`, and
- * hard-coding either one breaks the other.
- */
+* Find the pids cgroup from INSIDE this process, never a hard-coded path —
+* same reasoning as the memory layout: from inside the container the cgroup is
+* at the mount ROOT (`0::/`), from the host it is `<mount>/docker/<id>`, and
+* hard-coding either one breaks the other.
+*/
 export declare function resolveCgroupPidsLayout(fs: CgroupFileReader): CgroupPidsLayout | null;
 export interface ContainerPidsProbeDeps {
-    readonly logger: IScopedLogger;
-    readonly fs?: CgroupFileReader;
-    readonly now?: () => number;
-    /** How often the heartbeat line is written. Default 60 s. */
-    readonly heartbeatMs?: number;
-    /** Utilisation at which the heartbeat becomes a WARN. Default 0.8. */
-    readonly pressureFraction?: number;
+	readonly logger: IScopedLogger;
+	readonly fs?: CgroupFileReader;
+	readonly now?: () => number;
+	/** How often the heartbeat line is written. Default 60 s. */
+	readonly heartbeatMs?: number;
+	/** Utilisation at which the heartbeat becomes a WARN. Default 0.8. */
+	readonly pressureFraction?: number;
 }
 /**
- * The sampler.
- *
- * Its logging is deliberately different from the memory probe's, because the
- * operator asked for a DAY of regular readings before deciding whether to
- * raise the ceiling: there is a heartbeat, on its own cadence, whatever the
- * sampling tick is. Three lines exist and no more:
- *
- * 1. **Resolution**, once — the hierarchy that answered, or "no cgroup here",
- *    which is a fact about the node and not an error.
- * 2. **Heartbeat**, every `heartbeatMs` — current, ceiling, utilisation and
- *    the lifetime refusal count. INFO while there is room, WARN while we are
- *    above `pressureFraction`, and one INFO when it comes back down, so the
- *    log carries BOTH edges of a pressure episode rather than only its start.
- * 3. **A refusal**, immediately — the `pids.events` counter rose, so the
- *    kernel said no that many times since the last sample and some subsystem
- *    silently did without a thread. This one never waits for the heartbeat.
- */
+* The sampler.
+*
+* Its logging is deliberately different from the memory probe's, because the
+* operator asked for a DAY of regular readings before deciding whether to
+* raise the ceiling: there is a heartbeat, on its own cadence, whatever the
+* sampling tick is. Three lines exist and no more:
+*
+* 1. **Resolution**, once — the hierarchy that answered, or "no cgroup here",
+*    which is a fact about the node and not an error.
+* 2. **Heartbeat**, every `heartbeatMs` — current, ceiling, utilisation and
+*    the lifetime refusal count. INFO while there is room, WARN while we are
+*    above `pressureFraction`, and one INFO when it comes back down, so the
+*    log carries BOTH edges of a pressure episode rather than only its start.
+* 3. **A refusal**, immediately — the `pids.events` counter rose, so the
+*    kernel said no that many times since the last sample and some subsystem
+*    silently did without a thread. This one never waits for the heartbeat.
+*/
 export declare class ContainerPidsProbe {
-    private readonly logger;
-    private readonly fs;
-    private readonly now;
-    private readonly heartbeatMs;
-    private readonly pressureFraction;
-    private resolved;
-    private layout;
-    private lastHeartbeatAt;
-    private lastRefusals;
-    private underPressure;
-    constructor(deps: ContainerPidsProbeDeps);
-    /** Did this node resolve a pids cgroup at all? Absent is a reportable fact. */
-    get available(): boolean;
-    /** One reading, or `null` where there is no cgroup or it stopped answering. */
-    sample(): ContainerPidsSnapshot | null;
-    private resolveOnce;
-    private report;
-    /**
-     * The counter only ever rises, so a rise is a refusal that happened in this
-     * window. Reported the moment it is seen — never held for the heartbeat,
-     * because this is the line that says work was lost.
-     */
-    private reportRefusals;
-    private meta;
+	private readonly logger;
+	private readonly fs;
+	private readonly now;
+	private readonly heartbeatMs;
+	private readonly pressureFraction;
+	private resolved;
+	private layout;
+	private lastHeartbeatAt;
+	private lastRefusals;
+	private underPressure;
+	constructor(deps: ContainerPidsProbeDeps);
+	/** Did this node resolve a pids cgroup at all? Absent is a reportable fact. */
+	get available(): boolean;
+	/** One reading, or `null` where there is no cgroup or it stopped answering. */
+	sample(): ContainerPidsSnapshot | null;
+	private resolveOnce;
+	private report;
+	/**
+	* The counter only ever rises, so a rise is a refusal that happened in this
+	* window. Reported the moment it is seen — never held for the heartbeat,
+	* because this is the line that says work was lost.
+	*/
+	private reportRefusals;
+	private meta;
 }