@camstack/system 1.2.271 → 1.2.273

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

@@ -0,0 +1,112 @@
+import { IScopedLogger } from '@camstack/types';
+import { CgroupFileReader } from './cgroup-memory.js';
+/** Which hierarchy answered — reported so a reading is never ambiguous. */
+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;
+}
+/** 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;
+}
+/**
+ * `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.
+ */
+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;
+}): 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.
+ */
+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;
+}
+/**
+ * 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;
+}

package/dist/builtins/native-metrics/native-metrics.addon.d.ts

@@ -58,6 +58,7 @@ export default class NativeMetricsAddon extends BaseAddon<NativeMetricsConfig> {
      * cgroup once and latches.
      */
     private memoryProbe;
+    private pidsProbe;
     /** Hot tier for the container reading. Bounds in `container-memory-series.ts`. */
     private readonly memoryRing;
     /** Cold tier, HUB only — same reasoning as `loadStore`. */

package/dist/builtins/native-metrics/native-metrics.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-_YWIPtUH.js");
+const require_dist = require("../../dist-D5ONNqL6.js");
 let node_fs_promises = require("node:fs/promises");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
@@ -350,6 +350,211 @@ var ContainerMemoryProbe = class {
 		if (!first) this.logger.info("cgroup memory is answering again");
 	}
 };
+//#endregion
+//#region src/builtins/native-metrics/cgroup-pids.ts
+/**
+* `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 %.
+*/
+function parsePidsMax(text) {
+	const trimmed = text.trim();
+	if (trimmed.length === 0 || trimmed === "max") return null;
+	const value = Number(trimmed);
+	if (!Number.isFinite(value) || value < 0) return null;
+	return value;
+}
+/**
+* `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.
+*/
+function parsePidsEvents(text) {
+	for (const rawLine of text.split("\n")) {
+		const line = rawLine.trim();
+		if (line.length === 0) continue;
+		const space = line.indexOf(" ");
+		if (space <= 0) continue;
+		if (line.slice(0, space) !== "max") continue;
+		const value = Number(line.slice(space + 1).trim());
+		if (!Number.isFinite(value) || value < 0) return null;
+		return value;
+	}
+	return null;
+}
+/** Turn one layout's files into a snapshot. Pure over the text. */
+function buildContainerPidsSnapshot(input) {
+	const current = Number(input.currentText.trim());
+	if (!Number.isFinite(current) || current < 0) return null;
+	const max = input.maxText === null ? null : parsePidsMax(input.maxText);
+	return {
+		source: input.source,
+		current,
+		max,
+		usedFraction: max === null || max === 0 ? null : current / max,
+		refusals: input.eventsText === null ? null : parsePidsEvents(input.eventsText)
+	};
+}
+/**
+* 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.
+*/
+function resolveCgroupPidsLayout(fs) {
+	const selfText = fs.read("/proc/self/cgroup");
+	if (selfText === null) return null;
+	const entry = parseCgroupSelf(selfText);
+	if (entry === null) return null;
+	const suffix = entry.path === "/" ? "" : entry.path;
+	const candidates = entry.version === "v2" ? [`${CGROUP_MOUNT_ROOT}${suffix}`, CGROUP_MOUNT_ROOT] : [`${CGROUP_MOUNT_ROOT}/pids${suffix}`, `${CGROUP_MOUNT_ROOT}/pids`];
+	for (const directory of candidates) {
+		if (fs.read(`${directory}/pids.current`) === null) continue;
+		return {
+			source: entry.version === "v2" ? "cgroup-v2" : "cgroup-v1",
+			directory,
+			currentPath: `${directory}/pids.current`,
+			maxPath: `${directory}/pids.max`,
+			eventsPath: `${directory}/pids.events`
+		};
+	}
+	return null;
+}
+var DEFAULT_HEARTBEAT_MS = 6e4;
+var DEFAULT_PRESSURE_FRACTION = .8;
+/**
+* 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.
+*/
+var ContainerPidsProbe = class {
+	logger;
+	fs;
+	now;
+	heartbeatMs;
+	pressureFraction;
+	resolved = false;
+	layout = null;
+	lastHeartbeatAt = null;
+	lastRefusals = null;
+	underPressure = false;
+	constructor(deps) {
+		this.logger = deps.logger;
+		this.fs = deps.fs ?? nodeCgroupFileReader;
+		this.now = deps.now ?? Date.now;
+		this.heartbeatMs = deps.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+		this.pressureFraction = deps.pressureFraction ?? DEFAULT_PRESSURE_FRACTION;
+	}
+	/** Did this node resolve a pids cgroup at all? Absent is a reportable fact. */
+	get available() {
+		return this.layout !== null;
+	}
+	/** One reading, or `null` where there is no cgroup or it stopped answering. */
+	sample() {
+		const layout = this.resolveOnce();
+		if (layout === null) return null;
+		const currentText = this.fs.read(layout.currentPath);
+		if (currentText === null) return null;
+		const snapshot = buildContainerPidsSnapshot({
+			source: layout.source,
+			currentText,
+			maxText: this.fs.read(layout.maxPath),
+			eventsText: this.fs.read(layout.eventsPath)
+		});
+		if (snapshot === null) return null;
+		this.report(snapshot);
+		return snapshot;
+	}
+	resolveOnce() {
+		if (this.resolved) return this.layout;
+		this.resolved = true;
+		try {
+			this.layout = resolveCgroupPidsLayout(this.fs);
+		} catch (err) {
+			this.layout = null;
+			this.logger.warn("cgroup pids resolution failed — the pid ceiling will be ABSENT", { meta: { error: require_dist.errMsg(err) } });
+			return null;
+		}
+		if (this.layout === null) {
+			this.logger.info("no pids cgroup on this node — the pid ceiling is ABSENT, not unlimited, for every sample", { meta: {
+				platform: process.platform,
+				probed: "/proc/self/cgroup"
+			} });
+			return null;
+		}
+		this.logger.info("pid ceiling resolved from the cgroup", { meta: {
+			source: this.layout.source,
+			directory: this.layout.directory
+		} });
+		return this.layout;
+	}
+	report(snapshot) {
+		this.reportRefusals(snapshot);
+		const at = this.now();
+		const pressure = snapshot.usedFraction !== null && snapshot.usedFraction >= this.pressureFraction;
+		if (this.underPressure && !pressure) {
+			this.underPressure = false;
+			this.logger.info("pid pressure recovered — back under the guard fraction", { meta: this.meta(snapshot) });
+			this.lastHeartbeatAt = at;
+			return;
+		}
+		if (!(this.lastHeartbeatAt === null || at - this.lastHeartbeatAt >= this.heartbeatMs)) return;
+		this.lastHeartbeatAt = at;
+		this.underPressure = pressure;
+		if (pressure) {
+			this.logger.warn("pid ceiling is being approached — a refused clone() is silent work loss, and this container counts THREADS", { meta: this.meta(snapshot) });
+			return;
+		}
+		this.logger.info("pid ceiling", { meta: this.meta(snapshot) });
+	}
+	/**
+	* 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.
+	*/
+	reportRefusals(snapshot) {
+		const refusals = snapshot.refusals;
+		if (refusals === null) return;
+		const previous = this.lastRefusals;
+		this.lastRefusals = refusals;
+		if (previous === null || refusals <= previous) return;
+		this.logger.warn("the kernel REFUSED a fork at the pid ceiling — something asked for a thread and did not get one", { meta: {
+			...this.meta(snapshot),
+			refusedSinceLastSample: refusals - previous
+		} });
+	}
+	meta(snapshot) {
+		return {
+			current: snapshot.current,
+			max: snapshot.max,
+			usedPct: snapshot.usedFraction === null ? null : Math.round(snapshot.usedFraction * 1e3) / 10,
+			refusalsLifetime: snapshot.refusals,
+			source: snapshot.source
+		};
+	}
+};
 /**
 * One node's fixed-capacity circular buffer of samples.
 *
@@ -2809,6 +3014,7 @@ var NativeMetricsAddon = class NativeMetricsAddon extends require_dist.BaseAddon
 	* cgroup once and latches.
 	*/
 	memoryProbe = null;
+	pidsProbe = null;
 	/** Hot tier for the container reading. Bounds in `container-memory-series.ts`. */
 	memoryRing = new ContainerMemoryRing();
 	/** Cold tier, HUB only — same reasoning as `loadStore`. */
@@ -2895,6 +3101,7 @@ var NativeMetricsAddon = class NativeMetricsAddon extends require_dist.BaseAddon
 			});
 		}
 		this.memoryProbe = new ContainerMemoryProbe({ logger: this.ctx.logger.child("ContainerMemory") });
+		this.pidsProbe = new ContainerPidsProbe({ logger: this.ctx.logger.child("ContainerPids") });
 		this.snapshotTimer = setInterval(() => this.emitResourcesSnapshot(), METRICS_SNAPSHOT_INTERVAL_MS);
 		this.startProcessSnapshotTimer();
 		this.ctx.addDisposer(this.ctx.eventBus.subscribe({ category: require_dist.EventCategory.MetricsNodeProcessesSnapshot }, (event) => this.retainSnapshot(event.data.nodeId, event.data.timestamp, event.data.processes, event.data.containerMemory)));
@@ -3135,6 +3342,7 @@ var NativeMetricsAddon = class NativeMetricsAddon extends require_dist.BaseAddon
 		try {
 			const processes = await this.listNodeProcesses();
 			const containerMemory = this.memoryProbe?.sample() ?? null;
+			this.pidsProbe?.sample();
 			eventBus.emit(require_dist.createEvent(require_dist.EventCategory.MetricsNodeProcessesSnapshot, {
 				type: "node",
 				id: nodeId,

package/dist/builtins/native-metrics/native-metrics.addon.mjs

@@ -1,4 +1,4 @@
-import { Lt as reducePoints, Ot as metricsProviderCapability, Pn as EventCategory, Rt as resolveBucketMs, an as errMsg, bn as createEvent, lt as foldSnapshotByFunction, sn as BaseAddon } from "../../dist-Diz59Dhi.mjs";
+import { Lt as reducePoints, Ot as metricsProviderCapability, Pn as EventCategory, Rt as resolveBucketMs, an as errMsg, bn as createEvent, lt as foldSnapshotByFunction, sn as BaseAddon } from "../../dist-DrLhdcwI.mjs";
 import { access, readFile, readdir } from "node:fs/promises";
 import * as fs from "node:fs";
 import { constants, readFileSync } from "node:fs";
@@ -345,6 +345,211 @@ var ContainerMemoryProbe = class {
 		if (!first) this.logger.info("cgroup memory is answering again");
 	}
 };
+//#endregion
+//#region src/builtins/native-metrics/cgroup-pids.ts
+/**
+* `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 %.
+*/
+function parsePidsMax(text) {
+	const trimmed = text.trim();
+	if (trimmed.length === 0 || trimmed === "max") return null;
+	const value = Number(trimmed);
+	if (!Number.isFinite(value) || value < 0) return null;
+	return value;
+}
+/**
+* `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.
+*/
+function parsePidsEvents(text) {
+	for (const rawLine of text.split("\n")) {
+		const line = rawLine.trim();
+		if (line.length === 0) continue;
+		const space = line.indexOf(" ");
+		if (space <= 0) continue;
+		if (line.slice(0, space) !== "max") continue;
+		const value = Number(line.slice(space + 1).trim());
+		if (!Number.isFinite(value) || value < 0) return null;
+		return value;
+	}
+	return null;
+}
+/** Turn one layout's files into a snapshot. Pure over the text. */
+function buildContainerPidsSnapshot(input) {
+	const current = Number(input.currentText.trim());
+	if (!Number.isFinite(current) || current < 0) return null;
+	const max = input.maxText === null ? null : parsePidsMax(input.maxText);
+	return {
+		source: input.source,
+		current,
+		max,
+		usedFraction: max === null || max === 0 ? null : current / max,
+		refusals: input.eventsText === null ? null : parsePidsEvents(input.eventsText)
+	};
+}
+/**
+* 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.
+*/
+function resolveCgroupPidsLayout(fs) {
+	const selfText = fs.read("/proc/self/cgroup");
+	if (selfText === null) return null;
+	const entry = parseCgroupSelf(selfText);
+	if (entry === null) return null;
+	const suffix = entry.path === "/" ? "" : entry.path;
+	const candidates = entry.version === "v2" ? [`${CGROUP_MOUNT_ROOT}${suffix}`, CGROUP_MOUNT_ROOT] : [`${CGROUP_MOUNT_ROOT}/pids${suffix}`, `${CGROUP_MOUNT_ROOT}/pids`];
+	for (const directory of candidates) {
+		if (fs.read(`${directory}/pids.current`) === null) continue;
+		return {
+			source: entry.version === "v2" ? "cgroup-v2" : "cgroup-v1",
+			directory,
+			currentPath: `${directory}/pids.current`,
+			maxPath: `${directory}/pids.max`,
+			eventsPath: `${directory}/pids.events`
+		};
+	}
+	return null;
+}
+var DEFAULT_HEARTBEAT_MS = 6e4;
+var DEFAULT_PRESSURE_FRACTION = .8;
+/**
+* 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.
+*/
+var ContainerPidsProbe = class {
+	logger;
+	fs;
+	now;
+	heartbeatMs;
+	pressureFraction;
+	resolved = false;
+	layout = null;
+	lastHeartbeatAt = null;
+	lastRefusals = null;
+	underPressure = false;
+	constructor(deps) {
+		this.logger = deps.logger;
+		this.fs = deps.fs ?? nodeCgroupFileReader;
+		this.now = deps.now ?? Date.now;
+		this.heartbeatMs = deps.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+		this.pressureFraction = deps.pressureFraction ?? DEFAULT_PRESSURE_FRACTION;
+	}
+	/** Did this node resolve a pids cgroup at all? Absent is a reportable fact. */
+	get available() {
+		return this.layout !== null;
+	}
+	/** One reading, or `null` where there is no cgroup or it stopped answering. */
+	sample() {
+		const layout = this.resolveOnce();
+		if (layout === null) return null;
+		const currentText = this.fs.read(layout.currentPath);
+		if (currentText === null) return null;
+		const snapshot = buildContainerPidsSnapshot({
+			source: layout.source,
+			currentText,
+			maxText: this.fs.read(layout.maxPath),
+			eventsText: this.fs.read(layout.eventsPath)
+		});
+		if (snapshot === null) return null;
+		this.report(snapshot);
+		return snapshot;
+	}
+	resolveOnce() {
+		if (this.resolved) return this.layout;
+		this.resolved = true;
+		try {
+			this.layout = resolveCgroupPidsLayout(this.fs);
+		} catch (err) {
+			this.layout = null;
+			this.logger.warn("cgroup pids resolution failed — the pid ceiling will be ABSENT", { meta: { error: errMsg(err) } });
+			return null;
+		}
+		if (this.layout === null) {
+			this.logger.info("no pids cgroup on this node — the pid ceiling is ABSENT, not unlimited, for every sample", { meta: {
+				platform: process.platform,
+				probed: "/proc/self/cgroup"
+			} });
+			return null;
+		}
+		this.logger.info("pid ceiling resolved from the cgroup", { meta: {
+			source: this.layout.source,
+			directory: this.layout.directory
+		} });
+		return this.layout;
+	}
+	report(snapshot) {
+		this.reportRefusals(snapshot);
+		const at = this.now();
+		const pressure = snapshot.usedFraction !== null && snapshot.usedFraction >= this.pressureFraction;
+		if (this.underPressure && !pressure) {
+			this.underPressure = false;
+			this.logger.info("pid pressure recovered — back under the guard fraction", { meta: this.meta(snapshot) });
+			this.lastHeartbeatAt = at;
+			return;
+		}
+		if (!(this.lastHeartbeatAt === null || at - this.lastHeartbeatAt >= this.heartbeatMs)) return;
+		this.lastHeartbeatAt = at;
+		this.underPressure = pressure;
+		if (pressure) {
+			this.logger.warn("pid ceiling is being approached — a refused clone() is silent work loss, and this container counts THREADS", { meta: this.meta(snapshot) });
+			return;
+		}
+		this.logger.info("pid ceiling", { meta: this.meta(snapshot) });
+	}
+	/**
+	* 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.
+	*/
+	reportRefusals(snapshot) {
+		const refusals = snapshot.refusals;
+		if (refusals === null) return;
+		const previous = this.lastRefusals;
+		this.lastRefusals = refusals;
+		if (previous === null || refusals <= previous) return;
+		this.logger.warn("the kernel REFUSED a fork at the pid ceiling — something asked for a thread and did not get one", { meta: {
+			...this.meta(snapshot),
+			refusedSinceLastSample: refusals - previous
+		} });
+	}
+	meta(snapshot) {
+		return {
+			current: snapshot.current,
+			max: snapshot.max,
+			usedPct: snapshot.usedFraction === null ? null : Math.round(snapshot.usedFraction * 1e3) / 10,
+			refusalsLifetime: snapshot.refusals,
+			source: snapshot.source
+		};
+	}
+};
 /**
 * One node's fixed-capacity circular buffer of samples.
 *
@@ -2804,6 +3009,7 @@ var NativeMetricsAddon = class NativeMetricsAddon extends BaseAddon {
 	* cgroup once and latches.
 	*/
 	memoryProbe = null;
+	pidsProbe = null;
 	/** Hot tier for the container reading. Bounds in `container-memory-series.ts`. */
 	memoryRing = new ContainerMemoryRing();
 	/** Cold tier, HUB only — same reasoning as `loadStore`. */
@@ -2890,6 +3096,7 @@ var NativeMetricsAddon = class NativeMetricsAddon extends BaseAddon {
 			});
 		}
 		this.memoryProbe = new ContainerMemoryProbe({ logger: this.ctx.logger.child("ContainerMemory") });
+		this.pidsProbe = new ContainerPidsProbe({ logger: this.ctx.logger.child("ContainerPids") });
 		this.snapshotTimer = setInterval(() => this.emitResourcesSnapshot(), METRICS_SNAPSHOT_INTERVAL_MS);
 		this.startProcessSnapshotTimer();
 		this.ctx.addDisposer(this.ctx.eventBus.subscribe({ category: EventCategory.MetricsNodeProcessesSnapshot }, (event) => this.retainSnapshot(event.data.nodeId, event.data.timestamp, event.data.processes, event.data.containerMemory)));
@@ -3130,6 +3337,7 @@ var NativeMetricsAddon = class NativeMetricsAddon extends BaseAddon {
 		try {
 			const processes = await this.listNodeProcesses();
 			const containerMemory = this.memoryProbe?.sample() ?? null;
+			this.pidsProbe?.sample();
 			eventBus.emit(createEvent(EventCategory.MetricsNodeProcessesSnapshot, {
 				type: "node",
 				id: nodeId,

package/dist/builtins/platform-probe/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-_YWIPtUH.js");
+const require_dist = require("../../dist-D5ONNqL6.js");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_child_process = require("node:child_process");

package/dist/builtins/platform-probe/index.mjs

@@ -1,5 +1,5 @@
 import { o as __toESM } from "../../chunk-CNf5ZN-e.mjs";
-import { Gt as scoreRuntimes, Pn as EventCategory, Pt as platformProbeCapability, Sn as emitReadiness, an as errMsg, nt as enumerateInferenceDevices, sn as BaseAddon } from "../../dist-Diz59Dhi.mjs";
+import { Gt as scoreRuntimes, Pn as EventCategory, Pt as platformProbeCapability, Sn as emitReadiness, an as errMsg, nt as enumerateInferenceDevices, sn as BaseAddon } from "../../dist-DrLhdcwI.mjs";
 import * as fs from "node:fs";
 import { execFile } from "node:child_process";
 import * as os from "node:os";

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-_YWIPtUH.js");
+const require_dist = require("../../dist-D5ONNqL6.js");
 //#region src/builtins/remote-access-orchestrator/enabled-providers-reconcile.ts
 /**
 * Reconcile the durable `enabledProviders` set against authoritative

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { Pn as EventCategory, sn as BaseAddon } from "../../dist-Diz59Dhi.mjs";
+import { Pn as EventCategory, sn as BaseAddon } from "../../dist-DrLhdcwI.mjs";
 //#region src/builtins/remote-access-orchestrator/enabled-providers-reconcile.ts
 /**
 * Reconcile the durable `enabledProviders` set against authoritative

package/dist/builtins/snapshot/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-_YWIPtUH.js");
+const require_dist = require("../../dist-D5ONNqL6.js");
 const require_snapshot_courtesy = require("../../snapshot-courtesy-Cqs7GkOV.js");
 let zod = require("zod");
 let node_crypto = require("node:crypto");

package/dist/builtins/snapshot/index.mjs

@@ -1,4 +1,4 @@
-import { B as bareAddonId, Dn as nodePin, Jt as snapshotCapability, Pn as EventCategory, V as batteryCapability, Z as deriveBatteryPresence, a as BatteryStatusSchema, an as errMsg, dn as DeviceFeature, en as streamQualityLabel, pn as DeviceType, sn as BaseAddon } from "../../dist-Diz59Dhi.mjs";
+import { B as bareAddonId, Dn as nodePin, Jt as snapshotCapability, Pn as EventCategory, V as batteryCapability, Z as deriveBatteryPresence, a as BatteryStatusSchema, an as errMsg, dn as DeviceFeature, en as streamQualityLabel, pn as DeviceType, sn as BaseAddon } from "../../dist-DrLhdcwI.mjs";
 import { i as renderCourtesyOverlayJpeg, n as courtesyCacheKey, r as renderCourtesyJpeg } from "../../snapshot-courtesy-CZPvteq2.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";

package/dist/builtins/sqlite-storage/filesystem-storage.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-_YWIPtUH.js");
+const require_dist = require("../../dist-D5ONNqL6.js");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");

package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs

@@ -1,4 +1,4 @@
-import { Qt as storageProviderCapability, ct as filesystemBrowseCapability, sn as BaseAddon } from "../../dist-Diz59Dhi.mjs";
+import { Qt as storageProviderCapability, ct as filesystemBrowseCapability, sn as BaseAddon } from "../../dist-DrLhdcwI.mjs";
 import { randomUUID } from "node:crypto";
 import { mkdir, readdir, realpath, statfs } from "node:fs/promises";
 import * as path$1 from "node:path";