@camstack/system 1.2.101 → 1.2.103

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM$1, r as __exportAll, t as __commonJSMin$1 } from "./chunk-CNf5ZN-e.mjs";
-import { At as asNumber, B as extractNestedAddonId, Bt as parseJsonUnknown$1, Dt as ReadinessTimeoutError, Et as ReadinessRegistry, Ft as expandCapMethods, Gt as EventCategory$1, H as isArrayOutputSchema, Ht as resolveCapMount, J as lifecycleJobSchema, K as isVoidInput, Mt as createEvent, Nt as emitDownForOwnedCaps, Q as looseSchema, St as DEVICE_STATUS_METHOD, U as isCollectionArrayMethod, Ut as scopeKey, Vt as readinessKey, W as isObjectInput, Z as logLevelAtMost, bt as DATAPLANE_SECRET_HEADER$1, d as METHOD_ACCESS_MAP, f as RUNTIME_DEFAULTS, it as procedureAuthKey, jt as asString$1, kt as asJsonObject$1, ot as scopesAllowAddon, q as kebabToCamel, st as scopesAllowDeviceCap, t as ALL_CAPABILITY_DEFINITIONS, tt as objectInputDeclaresAddonId, vt as errMsg$1, xt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, y as addonSettingsCapability, zt as parseJsonObject } from "./dist-RbFV8cX7.mjs";
+import { At as asNumber, B as extractNestedAddonId, Bt as parseJsonUnknown$1, Dt as ReadinessTimeoutError, Et as ReadinessRegistry, Ft as expandCapMethods, Gt as EventCategory$1, H as isArrayOutputSchema, Ht as resolveCapMount, J as lifecycleJobSchema, K as isVoidInput, Mt as createEvent, Nt as emitDownForOwnedCaps, Q as looseSchema, St as DEVICE_STATUS_METHOD, U as isCollectionArrayMethod, Ut as scopeKey, Vt as readinessKey, W as isObjectInput, Z as logLevelAtMost, bt as DATAPLANE_SECRET_HEADER$1, d as METHOD_ACCESS_MAP, f as RUNTIME_DEFAULTS, it as procedureAuthKey, jt as asString$1, kt as asJsonObject$1, ot as scopesAllowAddon, q as kebabToCamel, st as scopesAllowDeviceCap, t as ALL_CAPABILITY_DEFINITIONS, tt as objectInputDeclaresAddonId, vt as errMsg$1, xt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, y as addonSettingsCapability, zt as parseJsonObject } from "./dist-DHKXob1m.mjs";
 import { AlertCenterAddon } from "./builtins/alerts/alerts.addon.mjs";
 import "./builtins/alerts/index.mjs";
 import { t as formatLogLine } from "./formatter-B7qW8bPJ.mjs";
@@ -493,9 +493,10 @@ function proxyToUpstream(opts) {
 * ask V8 for the pages back when the process is visibly holding more than it is
 * using — which is what `shouldReclaim` decides and what the heartbeat now does.
 *
-* The cost is a 250-450ms stop-the-world on the hub's router process, bounded to
-* once per `HEAP_RECLAIM_MIN_INTERVAL_MS`. The alternative, measured, is a
-* ratchet to 7.8GB and the OOM that ends it.
+* The cost is a stop-the-world on the hub's router process — 250-450ms when
+* first measured, 654ms on the largest pass seen since — bounded to once per
+* `HEAP_RECLAIM_MIN_INTERVAL_MS`. The alternative, measured, is a ratchet to
+* 7.8GB and the OOM that ends it.
 */
 /** Heartbeat period. Slow enough to be free, fast enough that the sample before
 *  a fatal is recent. */
@@ -533,14 +534,46 @@ function nextMode(current, usedRatio, escalateRatio = HEAP_WATCH_ESCALATE_RATIO,
 * Live calibration, both readings from the same hub minutes apart: 2491MB
 * stranded before the reclaim, 438MB after. 438MB is this process's irreducible
 * native floor (sqlite pages, libvips, sharp, thread stacks, node's own text) —
-* collecting against it would buy nothing and cost a stall every minute. 1536
-* sits clear of that floor and still fires ~1.1GB before the ratchet is worth
-* anything, so it triggers on the real condition and stops as soon as it is fixed.
+* collecting against it would buy nothing and cost a stall every minute.
+*
+* ## Why this came down from 1536 (2026-08-17)
+*
+* The trigger was originally set to fire only on an unmistakable strand. It
+* does, and the pass on the record works exactly as designed:
+*
+*     [mem] reclaim hub-main stranded=2365MB rss=4016MB→2368MB freed=1648MB took=654ms
+*
+* But the number it was protecting against changed. The host now runs with a
+* 24GiB cgroup ceiling and **no swap**, and is OOM-killing a neighbouring VM.
+* RSS this process is holding and not using is no longer merely untidy — it is
+* the headroom something else needed, and the OOM is triggered by the PEAK, not
+* by the average. A trigger of 1536 means the peak is allowed to stand 1.5GiB
+* above the floor before anything happens.
+*
+* 1024 is 2.3x the measured 438MB floor, so ordinary movement around the floor
+* can never trip it, and every pass that does fire still returns roughly
+* `1024 - 438` ≈ **580MB minimum** — a real return for a 250-650ms stall,
+* not a stall spent collecting noise.
 */
-var HEAP_RECLAIM_TRIGGER_MB = 1536;
-/** Floor on how often the stop-the-world may run. 250-450ms measured, so ten
-*  minutes keeps the worst case under 0.1% of the router's time. */
-var HEAP_RECLAIM_MIN_INTERVAL_MS = 6e5;
+var HEAP_RECLAIM_TRIGGER_MB = 1024;
+/**
+* Floor on how often the stop-the-world may run.
+*
+* Ten minutes was chosen to keep the worst case under 0.1% of the router's
+* time. The worst case is not what governs the cost, though: the reclaim only
+* runs when {@link shouldReclaim} says the process is genuinely stranded, and
+* after a pass it is at the ~438MB floor. Live off-heap growth was measured at
+* roughly 3GB/2h ≈ 25MB/min, so re-stranding the ~580MB needed to qualify again
+* takes on the order of **20 minutes** — well outside any floor considered
+* here. In steady state this constant therefore costs nothing at all.
+*
+* What it does govern is a BURST, which is the only case that matters on a host
+* with no swap: the ten-minute floor let a peak that re-formed in seconds stand
+* for ten minutes. Two minutes bounds that, and even the pathological case of a
+* process that re-strands instantly costs 654ms per 120s — 0.55% of the
+* router's time, against a ~1.5GiB peak it removes each pass.
+*/
+var HEAP_RECLAIM_MIN_INTERVAL_MS = 12e4;
 var MB = (bytes) => Math.round(bytes / 1048576);
 /**
 * Build a sample from raw readings. Pure so the thresholds are testable without
@@ -616,8 +649,8 @@ function format$1(label, s) {
 function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEAP_WATCH_INTERVAL_MS, reclaimOptions) {
 	const readMemory = reclaimOptions?.readMemory ?? (() => process.memoryUsage());
 	const now = reclaimOptions?.now ?? (() => Date.now());
-	const triggerMb = reclaimOptions?.triggerMb ?? 1536;
-	const minIntervalMs = reclaimOptions?.minIntervalMs ?? 6e5;
+	const triggerMb = reclaimOptions?.triggerMb ?? 1024;
+	const minIntervalMs = reclaimOptions?.minIntervalMs ?? 12e4;
 	const fastIntervalMs = reclaimOptions?.fastIntervalMs ?? 2e3;
 	const escalateRatio = reclaimOptions?.escalateRatio ?? .7;
 	const deescalateRatio = reclaimOptions?.deescalateRatio ?? .6;
@@ -960,6 +993,26 @@ function addonBucketKey(addonId) {
 */
 var PRUNE_TARGET_RATIO = .9;
 /**
+* Default ceiling on retained entries across every bucket.
+*
+* This used to be `null` — no aggregate bound at all — and the only thing
+* holding hub-main's log memory was `perAddonCapacity x buckets`, a product
+* that grows with the roster. Measured on the live cluster: 37 forked runners
+* on the hub plus its in-process builtins, and hub-main additionally ingests
+* every line from both agents, so ~60 buckets is the ordinary case and
+* 60 x 5000 = 300k retained entries.
+*
+* A realistic entry (timestamp, level, scope, ~70-char message, three tags, no
+* `meta`) measures **~306 B retained** in V8. So the old unbounded case is
+* ~92MB of a hub process that is being asked to fit inside a cgroup with a
+* neighbour to protect, and 50_000 is **~15MB**.
+*
+* 50_000 across a ~60-bucket roster is ~830 entries per addon on average while
+* still letting a single chatty addon hold its full 5000-entry ring — the
+* partitioning is not weakened, only the total is held.
+*/
+var DEFAULT_MAX_TOTAL_LOG_ENTRIES = 5e4;
+/**
 * A log buffer partitioned into one fixed-capacity {@link LogRingBuffer} per
 * `addonId`. A chatty addon (e.g. detection-pipeline) only ever evicts its OWN
 * bucket, so a quiet addon's sparse lines (e.g. a HomeAssistant `image` entity)
@@ -968,38 +1021,55 @@ var PRUNE_TARGET_RATIO = .9;
 * Drop-in for {@link LogRingBuffer} from {@link LogManager}'s perspective —
 * exposes the same `push` / `getAll` / `query` / `clear` surface.
 *
-* ## Two bounds, doing different jobs
+* ## Three bounds, doing different jobs
 *
 * **`perAddonCapacity`** is a HARD bound: each bucket is a fixed-size ring, so
 * total memory can never exceed `perAddonCapacity × buckets` whatever else
 * happens. This is the safety net.
 *
-* **`maxTotalEntries`** is a SOFT target across all buckets, and it exists because
-* the hard bound scales with addon count — 70 addons × 5000 is a lot of retained
-* entries on a small box. When the total is exceeded, the sweep discards only
-* entries at or below `pruneLevel` (default `debug`), oldest first, from the
+* **`maxTotalEntries`** targets the total across all buckets, and it exists because
+* the hard bound scales with addon count — 60 buckets × 5000 was 300k retained
+* entries on the live hub. When the total is exceeded, the sweep first discards
+* only entries at or below `pruneLevel` (default `debug`), oldest first, from the
 * largest buckets first.
 *
-* It is deliberately soft. Meeting a total cap by discarding `warn` and `error`
-* would trade the entries that explain an incident for entries about frame
-* timings; if pruning every prunable entry still leaves the total above the cap,
-* the buffer stays above it and the hard per-bucket bound is what holds. A cap
-* that can evict an error is not a feature.
+* It is deliberately soft ON A LIVE BUCKET. Meeting a total cap by discarding
+* `warn` and `error` from an addon that is still logging would trade the entries
+* that explain an incident for entries about frame timings. A cap that can evict
+* a live addon's error is not a feature.
 *
 * Largest-bucket-first because the noisy addon is the one creating the pressure —
 * the same principle that motivated partitioning in the first place.
+*
+* **`maxBuckets`, and bucket eviction, are the hard backstop.** Pruning alone
+* cannot bound this structure: it may only discard at or below `pruneLevel`, so
+* a bucket full of `info` from an addon that no longer exists was immortal, and
+* the roster the product scales with is not fixed. When pruning cannot reach the
+* target — or the bucket count exceeds `maxBuckets` — whole buckets are dropped
+* **least-recently-WRITTEN first**, and never the bucket currently being written
+* to. That is precisely the dead addon's bucket, and it is precisely not the
+* bucket of the addon whose incident is in progress.
 */
 var PartitionedLogBuffer = class {
 	buffers = /* @__PURE__ */ new Map();
+	/**
+	* Bucket key → the write ordinal of its last `push`. A monotonic counter, not
+	* a clock: eviction order must follow the order writes actually happened, and
+	* a wall clock that steps backwards would pick the wrong victim.
+	*/
+	lastWriteSeq = /* @__PURE__ */ new Map();
+	writeSeq = 0;
 	perAddonCapacity;
 	maxTotalEntries;
 	pruneLevel;
+	maxBuckets;
 	/** Running total, so `push` does not walk every bucket to decide. */
 	totalEntries = 0;
 	constructor(perAddonCapacity = 5e3, options = {}) {
 		this.perAddonCapacity = options.perAddonCapacity ?? perAddonCapacity;
-		this.maxTotalEntries = options.maxTotalEntries ?? null;
+		this.maxTotalEntries = options.maxTotalEntries === void 0 ? DEFAULT_MAX_TOTAL_LOG_ENTRIES : options.maxTotalEntries;
 		this.pruneLevel = options.pruneLevel ?? "debug";
+		this.maxBuckets = options.maxBuckets === void 0 ? 128 : options.maxBuckets;
 	}
 	/**
 	* Apply new limits at runtime. Shrinking takes effect as entries are pushed
@@ -1012,6 +1082,7 @@ var PartitionedLogBuffer = class {
 		if (options.perAddonCapacity !== void 0 && options.perAddonCapacity > 0) this.perAddonCapacity = options.perAddonCapacity;
 		if (options.maxTotalEntries !== void 0) this.maxTotalEntries = options.maxTotalEntries;
 		if (options.pruneLevel !== void 0) this.pruneLevel = options.pruneLevel;
+		if (options.maxBuckets !== void 0) this.maxBuckets = options.maxBuckets;
 	}
 	bufferFor(key) {
 		let buf = this.buffers.get(key);
@@ -1022,34 +1093,82 @@ var PartitionedLogBuffer = class {
 		return buf;
 	}
 	push(entry) {
-		const buf = this.bufferFor(addonBucketKey(entry.tags?.addonId));
+		const key = addonBucketKey(entry.tags?.addonId);
+		const buf = this.bufferFor(key);
 		const before = buf.size();
 		buf.push(entry);
 		this.totalEntries += buf.size() - before;
-		if (this.maxTotalEntries !== null && this.totalEntries > this.maxTotalEntries) this.enforceTotalCap(this.maxTotalEntries);
+		this.lastWriteSeq.set(key, ++this.writeSeq);
+		if (this.maxBuckets !== null && this.buffers.size > this.maxBuckets) this.evictBuckets(this.buffers.size - this.maxBuckets, key);
+		if (this.maxTotalEntries !== null && this.totalEntries > this.maxTotalEntries) this.enforceTotalCap(this.maxTotalEntries, key);
 	}
 	/**
-	* Bring the total down to `PRUNE_TARGET_RATIO × cap` by discarding prunable
-	* entries, largest bucket first. Stops early when nothing prunable is left —
-	* see the class docblock on why that is the correct outcome rather than a
-	* failure to enforce.
-	*/
-	enforceTotalCap(cap) {
+	* Bring the total down to `PRUNE_TARGET_RATIO × cap`.
+	*
+	* Two passes, in this order and no other: first discard prunable entries,
+	* largest bucket first, which is free of information cost. Only if that
+	* cannot reach the target does the second pass drop WHOLE buckets,
+	* least-recently-written first — the bound has to hold even when every
+	* retained entry is above `pruneLevel`, and a bucket nobody has written to is
+	* the cheapest thing in the structure to lose.
+	*/
+	enforceTotalCap(cap, protectedKey) {
 		const target = Math.max(1, Math.floor(cap * PRUNE_TARGET_RATIO));
 		let deficit = this.totalEntries - target;
 		if (deficit <= 0) return;
-		const bySizeDesc = [...this.buffers.values()].sort((a, b) => b.size() - a.size());
-		for (const buf of bySizeDesc) {
+		const bySizeDesc = [...this.buffers.entries()].toSorted((a, b) => b[1].size() - a[1].size());
+		for (const [key, buf] of bySizeDesc) {
 			if (deficit <= 0) break;
 			const removed = buf.pruneOldestAtOrBelow(this.pruneLevel, deficit);
 			this.totalEntries -= removed;
 			deficit -= removed;
+			if (buf.size() === 0) this.dropBucket(key);
 		}
+		if (deficit > 0) this.evictBucketsUntil(target, protectedKey);
+	}
+	/**
+	* Drop whole buckets, least-recently-WRITTEN first, until the total is at or
+	* below `target`. Never touches `protectedKey` (the bucket being written to
+	* right now) and always leaves at least one bucket standing.
+	*/
+	evictBucketsUntil(target, protectedKey) {
+		for (const key of this.evictionOrder(protectedKey)) {
+			if (this.totalEntries <= target || this.buffers.size <= 1) return;
+			this.dropBucket(key);
+		}
+	}
+	/** Drop exactly `count` buckets, least-recently-written first. */
+	evictBuckets(count, protectedKey) {
+		let remaining = count;
+		for (const key of this.evictionOrder(protectedKey)) {
+			if (remaining <= 0 || this.buffers.size <= 1) return;
+			this.dropBucket(key);
+			remaining -= 1;
+		}
+	}
+	/** Bucket keys ordered least-recently-written first, excluding `protectedKey`.
+	*  A bucket with no recorded write sorts first — it can only be a leftover. */
+	evictionOrder(protectedKey) {
+		return [...this.buffers.keys()].filter((key) => key !== protectedKey).toSorted((a, b) => (this.lastWriteSeq.get(a) ?? 0) - (this.lastWriteSeq.get(b) ?? 0));
+	}
+	/** Remove a bucket and everything that indexes it. An empty ring left behind
+	*  is the leak this class shipped with — the map only ever grew. */
+	dropBucket(key) {
+		const buf = this.buffers.get(key);
+		if (buf === void 0) return;
+		this.totalEntries -= buf.size();
+		this.buffers.delete(key);
+		this.lastWriteSeq.delete(key);
 	}
 	/** Entries retained across every bucket. */
 	size() {
 		return this.totalEntries;
 	}
+	/** Buckets currently retained. Observability for the aggregate bound — an
+	*  addon roster that only ever grows is what this class had to stop doing. */
+	bucketCount() {
+		return this.buffers.size;
+	}
 	/** Every retained entry across all buckets, newest-first (mirrors
 	*  {@link LogRingBuffer.getAll}). Used to replay history to a destination. */
 	getAll() {
@@ -1077,13 +1196,25 @@ var PartitionedLogBuffer = class {
 		if (pinned !== null) {
 			const removed = this.buffers.get(pinned)?.clear(filter) ?? 0;
 			this.totalEntries -= removed;
+			this.dropIfEmpty(pinned);
 			return removed;
 		}
 		let removed = 0;
-		for (const buf of this.buffers.values()) removed += buf.clear(filter);
+		for (const [key, buf] of [...this.buffers.entries()]) {
+			removed += buf.clear(filter);
+			this.dropIfEmpty(key);
+		}
 		this.totalEntries -= removed;
 		return removed;
 	}
+	/** An emptied bucket is removed rather than left as an empty ring: the map
+	*  used to grow with every addon id that ever logged and never shrink. */
+	dropIfEmpty(key) {
+		if (this.buffers.get(key)?.size() === 0) {
+			this.buffers.delete(key);
+			this.lastWriteSeq.delete(key);
+		}
+	}
 	/** The bucket key a filter pins to via `tags.addonId`, or null when the
 	*  filter doesn't constrain the addon (→ scan all buckets). */
 	pinnedAddonKey(filter) {
@@ -1181,11 +1312,13 @@ var LogManager = class {
 	* `perAddonCapacity` bounds EACH addon's bucket, not the total — a chatty addon
 	* evicts only its own lines, so quiet addons keep their sparse history.
 	*
-	* `options.maxTotalEntries` adds a soft ceiling across all buckets, because the
-	* per-bucket bound scales with addon count. When it is exceeded, only entries at
-	* or below `options.pruneLevel` (default `debug`) are discarded — `warn` and
-	* `error` are never evicted to satisfy it. Both default to the previous
-	* behaviour: no total cap. See {@link PartitionedLogBuffer}.
+	* `options.maxTotalEntries` ceilings the total across all buckets, because the
+	* per-bucket bound scales with addon count, and `options.maxBuckets` ceilings the
+	* bucket count itself. When the total is exceeded, entries at or below
+	* `options.pruneLevel` (default `debug`) are discarded first — a live addon's
+	* `warn`/`error` are never evicted to satisfy it — and only if that cannot reach
+	* the target are whole least-recently-written buckets dropped. Both bounds are ON
+	* by default; pass an explicit `null` to opt out. See {@link PartitionedLogBuffer}.
 	*/
 	constructor(perAddonCapacity = 5e3, options = {}) {
 		this.ringBuffer = new PartitionedLogBuffer(perAddonCapacity, options);
@@ -94296,33 +94429,45 @@ async function getPidStats$1(pids) {
 		});
 	});
 }
+var EMPTY_HEAP_DECLARATION = {
+	profile: void 0,
+	maxOldSpaceMb: void 0
+};
 /**
-* Resolve the declared heap profile for one addon by reading its package.json manifest
-* (`camstack.addons[].execution.heapProfile`). `addonDir` points at the addon's built `dist`, so the
-* manifest is one level up; we also try `addonDir` itself for layouts where it IS the package root.
+* Resolve the declared heap profile + old-space ceiling for one addon by reading its package.json
+* manifest (`camstack.addons[].execution.{heapProfile,maxOldSpaceMb}`). `addonDir` points at the
+* addon's built `dist`, so the manifest is one level up; we also try `addonDir` itself for layouts
+* where it IS the package root.
 * Result is cached per (dir,id) — spawns are infrequent but a runner may re-spawn on crash/restart.
-* Returns `undefined` when the manifest is unreadable or declares no profile → treated as light.
+* Returns an empty declaration when the manifest is unreadable → treated as light, default ceiling.
 */
 var heapProfileCache = /* @__PURE__ */ new Map();
-function readAddonHeapProfile(spec) {
+function readAddonHeapDeclaration(spec) {
 	const cacheKey = `${spec.addonDir}::${spec.addonId}`;
 	const cached = heapProfileCache.get(cacheKey);
-	if (cached !== void 0 || heapProfileCache.has(cacheKey)) return cached;
-	let profile;
+	if (cached !== void 0) return cached;
+	let declaration = EMPTY_HEAP_DECLARATION;
 	for (const manifestPath of [path$39.join(spec.addonDir, "package.json"), path$39.join(path$39.dirname(spec.addonDir), "package.json")]) try {
 		const raw = fs$17.readFileSync(manifestPath, "utf8");
 		const parsed = JSON.parse(raw);
-		profile = extractHeapProfile(parsed, spec.addonId);
-		if (profile !== void 0) break;
+		const profile = extractHeapProfile(parsed, spec.addonId);
+		const maxOldSpaceMb = extractMaxOldSpaceMb(parsed, spec.addonId);
+		if (profile !== void 0 || maxOldSpaceMb !== void 0) {
+			declaration = {
+				profile,
+				maxOldSpaceMb
+			};
+			break;
+		}
 		if (manifestHasAddon(parsed, spec.addonId)) break;
 	} catch {}
-	heapProfileCache.set(cacheKey, profile);
-	return profile;
+	heapProfileCache.set(cacheKey, declaration);
+	return declaration;
 }
 /**
-* Drop the cached heap profile for each addon so the NEXT `readAddonHeapProfile`
+* Drop the cached heap declaration for each addon so the NEXT `readAddonHeapDeclaration`
 * re-reads the manifest from disk. Called on operator-driven spawns / restarts
-* (a deploy may have changed the addon's `execution.heapProfile`); the
+* (a deploy may have changed `execution.heapProfile` / `execution.maxOldSpaceMb`); the
 * crash-respawn fast path deliberately does NOT invalidate — a crashing runner
 * has the same on-disk manifest, so re-reading it is pure overhead.
 */
@@ -94336,6 +94481,10 @@ function extractHeapProfile(parsed, addonId) {
 	const value = readManifestAddons(parsed).find((a) => a.id === addonId)?.execution?.heapProfile;
 	return value === "heavy" || value === "light" ? value : void 0;
 }
+function extractMaxOldSpaceMb(parsed, addonId) {
+	const value = readManifestAddons(parsed).find((a) => a.id === addonId)?.execution?.maxOldSpaceMb;
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : void 0;
+}
 function readManifestAddons(parsed) {
 	if (typeof parsed !== "object" || parsed === null) return [];
 	const camstack = parsed.camstack;
@@ -94348,25 +94497,78 @@ function readManifestAddons(parsed) {
 * Everything else (the un-annotated default) is a light control-plane runner. No hard-coded names.
 */
 function isHeavyRunner(addons) {
-	return addons.some((a) => readAddonHeapProfile(a) === "heavy");
+	return addons.some((a) => readAddonHeapDeclaration(a).profile === "heavy");
+}
+/**
+* Default old-space ceiling for a HEAVY runner, in MB.
+*
+* ## Why a heavy runner needs a ceiling at all
+*
+* `heapProfile: 'heavy'` used to mean "V8 defaults", i.e. no `--max-old-space-size` — which on this
+* host is V8's own memory-derived default (multiple GB). Nothing then bounds a burst, and V8 does
+* not hand committed pages back (the long argument for that is in `kernel/heap-watch.ts`), so a
+* one-off burst becomes the runner's permanent RSS.
+*
+* Measured on the live hub, 2026-08-17: the `recorder` runner reaches **2122 MB RSS** and stays
+* there after the deferred archive walk (99,809 segments in 84s), while the `RecordingIndex` it
+* actually retains is arithmetically ~21 MB (a `SegmentRow` is 5 numbers + 3 strings ≈ 207 B). The
+* same addon on two agent nodes carrying the same code and a smaller archive sits at **58 MB**.
+* The ~2 GB is walk garbage held as high-water in a heap that had no reason to collect it.
+*
+* ## Why 1024
+*
+* From the same live topology snapshot, every heavy runner's FULL RSS — which is a strict
+* over-estimate of its old space, since it also contains native allocations, `external` and
+* `arrayBuffers`, none of which `--max-old-space-size` bounds:
+*
+*   detection 471 MB · provider-reolink 507 MB · pipeline-orchestrator 238 MB · ml 218 MB ·
+*   snapshot 185 MB · decoder-nodeav 174 MB · audio-analyzer 170 MB
+*
+* 1024 MB clears the largest of those by ~2x while cutting the recorder's observed ratchet by
+* more than half. It is a CEILING, not a target: a runner that fits today keeps behaving exactly
+* as it does now, because V8 only collects harder as it approaches the limit.
+*
+* A runner whose working set genuinely does not fit declares its own number in its manifest
+* (`execution.maxOldSpaceMb`) — the number belongs next to the addon that knows its working set.
+* `stream-broker` (1323 MB measured, frame buffers) is the one shipped addon that does.
+*/
+var HEAVY_MAX_OLD_MB_DEFAULT = 1024;
+/**
+* The runner's old-space ceiling in MB, or 0 for "uncapped".
+*
+* The runner takes the MAXIMUM ceiling any co-located addon declares — co-location must never
+* silence the hungriest member (D2/D29: a runner is respawned as a whole, so an OOM caused by
+* under-sizing one member kills every addon in the group). An addon declaring `0` therefore lifts
+* the cap for the whole runner, which is the intended escape hatch.
+*/
+function runnerMaxOldSpaceMb(addons, heavy) {
+	const envDefault = heavy ? positiveIntEnv("CAMSTACK_RUNNER_HEAVY_MAX_OLD_MB", HEAVY_MAX_OLD_MB_DEFAULT) : positiveIntEnv("CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB", 0);
+	const declared = addons.map((a) => readAddonHeapDeclaration(a).maxOldSpaceMb).filter((mb) => mb !== void 0);
+	if (declared.length === 0) return envDefault;
+	if (declared.includes(0)) return 0;
+	return Math.max(...declared);
 }
 /**
 * Per-placement V8 heap flags (Block D). LIGHT runners cap their young generation
-* (`--max-semi-space-size`) to reclaim V8's over-reservation — a measured ~15 MB/runner win.
-* HEAVY runners keep V8 defaults. The old-space cap is opt-in via env (unset = uncapped = no OOM
-* risk) so it can be enabled after before/after measurement on the real cluster.
+* (`--max-semi-space-size`) to reclaim V8's over-reservation — a measured ~15 MB/runner win — and
+* keep an opt-in old-space cap (`CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`, unset = uncapped). HEAVY
+* runners keep V8's default young generation but ALWAYS carry an old-space ceiling; see
+* {@link HEAVY_MAX_OLD_MB_DEFAULT} for why, and how a runner declares its own.
 *
 * Kill-switch: `CAMSTACK_RUNNER_HEAP_TUNING=off` disables all flags (recover without a rebuild).
 * Overrides: `CAMSTACK_RUNNER_LIGHT_SEMI_SPACE_MB` (default 2), `CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB`
-* (default unset = no old-space cap).
+* (default unset = no old-space cap), `CAMSTACK_RUNNER_HEAVY_MAX_OLD_MB`
+* (default {@link HEAVY_MAX_OLD_MB_DEFAULT}; `0` restores the old uncapped behaviour).
 */
 function runnerHeapFlags(addons) {
 	if (process.env["CAMSTACK_RUNNER_HEAP_TUNING"] === "off") return [];
-	if (isHeavyRunner(addons)) return [];
-	const semiMb = positiveIntEnv("CAMSTACK_RUNNER_LIGHT_SEMI_SPACE_MB", 2);
-	const oldMb = positiveIntEnv("CAMSTACK_RUNNER_LIGHT_MAX_OLD_MB", 0);
+	const heavy = isHeavyRunner(addons);
 	const flags = [];
-	if (semiMb > 0) flags.push(`--max-semi-space-size=${semiMb}`);
+	if (!heavy) {
+		const semiMb = positiveIntEnv("CAMSTACK_RUNNER_LIGHT_SEMI_SPACE_MB", 2);
+		if (semiMb > 0) flags.push(`--max-semi-space-size=${semiMb}`);
+	}
+	const oldMb = runnerMaxOldSpaceMb(addons, heavy);
 	if (oldMb > 0) flags.push(`--max-old-space-size=${oldMb}`);
 	return flags;
 }

package/dist/kernel/config-schema.d.ts

@@ -85,18 +85,22 @@ export type AppConfig = BootstrapConfig & {
          */
         perAddonLogBufferSize?: number;
         /**
-         * SOFT ceiling on retained entries across every addon bucket. `null` (the
-         * default) means the per-addon rings are the only bound — the historical
-         * behaviour, unchanged unless you set this.
+         * Ceiling on retained entries across every addon bucket.
          *
-         * Set it when `perAddonLogBufferSize × addons` is more than the box can spare:
-         * 70 addons × 5000 is 350k retained entries, which is a lot on a mini PC.
+         * UNSET (the normal case) takes `DEFAULT_MAX_TOTAL_LOG_ENTRIES` — the buffer is
+         * bounded in aggregate out of the box. It has to be: `perAddonLogBufferSize ×
+         * addons` grows with the roster, and hub-main ingests from every local runner
+         * AND every agent, so the measured ~60-bucket hub retained ~300k entries
+         * (~92MB at ~306 B/entry) with no aggregate bound at all.
          *
-         * Soft, and deliberately so: it is met by discarding only entries at or below
-         * `logBufferPruneLevel`. If pruning every prunable entry still leaves the total
-         * above this number, the buffer stays above it. A cap that could evict an
-         * `error` would trade the lines that explain an incident for lines about frame
-         * timings.
+         * Set a number to tune it. Set an explicit `null` to opt out entirely — the
+         * per-addon rings then become the only bound again.
+         *
+         * It is met by discarding entries at or below `logBufferPruneLevel` FIRST, so a
+         * live addon's `warn`/`error` are never traded for lines about frame timings.
+         * Only when that cannot reach the target are whole least-recently-WRITTEN
+         * buckets dropped — a bound that pruning alone cannot hold is not a bound, and
+         * the bucket nobody has written to is the cheapest thing in the buffer to lose.
          */
         maxTotalLogBufferSize?: number | null;
         /**

package/dist/kernel/heap-watch.d.ts

@@ -59,14 +59,46 @@ export declare function nextMode(current: HeapWatchMode, usedRatio: number, esca
  * Live calibration, both readings from the same hub minutes apart: 2491MB
  * stranded before the reclaim, 438MB after. 438MB is this process's irreducible
  * native floor (sqlite pages, libvips, sharp, thread stacks, node's own text) —
- * collecting against it would buy nothing and cost a stall every minute. 1536
- * sits clear of that floor and still fires ~1.1GB before the ratchet is worth
- * anything, so it triggers on the real condition and stops as soon as it is fixed.
+ * collecting against it would buy nothing and cost a stall every minute.
+ *
+ * ## Why this came down from 1536 (2026-08-17)
+ *
+ * The trigger was originally set to fire only on an unmistakable strand. It
+ * does, and the pass on the record works exactly as designed:
+ *
+ *     [mem] reclaim hub-main stranded=2365MB rss=4016MB→2368MB freed=1648MB took=654ms
+ *
+ * But the number it was protecting against changed. The host now runs with a
+ * 24GiB cgroup ceiling and **no swap**, and is OOM-killing a neighbouring VM.
+ * RSS this process is holding and not using is no longer merely untidy — it is
+ * the headroom something else needed, and the OOM is triggered by the PEAK, not
+ * by the average. A trigger of 1536 means the peak is allowed to stand 1.5GiB
+ * above the floor before anything happens.
+ *
+ * 1024 is 2.3x the measured 438MB floor, so ordinary movement around the floor
+ * can never trip it, and every pass that does fire still returns roughly
+ * `1024 - 438` ≈ **580MB minimum** — a real return for a 250-650ms stall,
+ * not a stall spent collecting noise.
+ */
+export declare const HEAP_RECLAIM_TRIGGER_MB = 1024;
+/**
+ * Floor on how often the stop-the-world may run.
+ *
+ * Ten minutes was chosen to keep the worst case under 0.1% of the router's
+ * time. The worst case is not what governs the cost, though: the reclaim only
+ * runs when {@link shouldReclaim} says the process is genuinely stranded, and
+ * after a pass it is at the ~438MB floor. Live off-heap growth was measured at
+ * roughly 3GB/2h ≈ 25MB/min, so re-stranding the ~580MB needed to qualify again
+ * takes on the order of **20 minutes** — well outside any floor considered
+ * here. In steady state this constant therefore costs nothing at all.
+ *
+ * What it does govern is a BURST, which is the only case that matters on a host
+ * with no swap: the ten-minute floor let a peak that re-formed in seconds stand
+ * for ten minutes. Two minutes bounds that, and even the pathological case of a
+ * process that re-strands instantly costs 654ms per 120s — 0.55% of the
+ * router's time, against a ~1.5GiB peak it removes each pass.
  */
-export declare const HEAP_RECLAIM_TRIGGER_MB = 1536;
-/** Floor on how often the stop-the-world may run. 250-450ms measured, so ten
- *  minutes keeps the worst case under 0.1% of the router's time. */
-export declare const HEAP_RECLAIM_MIN_INTERVAL_MS = 600000;
+export declare const HEAP_RECLAIM_MIN_INTERVAL_MS = 120000;
 export interface HeapSample {
     readonly rssMb: number;
     readonly heapUsedMb: number;

package/dist/kernel/moleculer/process-service.d.ts

@@ -5,6 +5,40 @@ interface RunnerAddonSpec {
     readonly addonId: string;
     readonly addonDir: string;
 }
+/**
+ * Default old-space ceiling for a HEAVY runner, in MB.
+ *
+ * ## Why a heavy runner needs a ceiling at all
+ *
+ * `heapProfile: 'heavy'` used to mean "V8 defaults", i.e. no `--max-old-space-size` — which on this
+ * host is V8's own memory-derived default (multiple GB). Nothing then bounds a burst, and V8 does
+ * not hand committed pages back (the long argument for that is in `kernel/heap-watch.ts`), so a
+ * one-off burst becomes the runner's permanent RSS.
+ *
+ * Measured on the live hub, 2026-08-17: the `recorder` runner reaches **2122 MB RSS** and stays
+ * there after the deferred archive walk (99,809 segments in 84s), while the `RecordingIndex` it
+ * actually retains is arithmetically ~21 MB (a `SegmentRow` is 5 numbers + 3 strings ≈ 207 B). The
+ * same addon on two agent nodes carrying the same code and a smaller archive sits at **58 MB**.
+ * The ~2 GB is walk garbage held as high-water in a heap that had no reason to collect it.
+ *
+ * ## Why 1024
+ *
+ * From the same live topology snapshot, every heavy runner's FULL RSS — which is a strict
+ * over-estimate of its old space, since it also contains native allocations, `external` and
+ * `arrayBuffers`, none of which `--max-old-space-size` bounds:
+ *
+ *   detection 471 MB · provider-reolink 507 MB · pipeline-orchestrator 238 MB · ml 218 MB ·
+ *   snapshot 185 MB · decoder-nodeav 174 MB · audio-analyzer 170 MB
+ *
+ * 1024 MB clears the largest of those by ~2x while cutting the recorder's observed ratchet by
+ * more than half. It is a CEILING, not a target: a runner that fits today keeps behaving exactly
+ * as it does now, because V8 only collects harder as it approaches the limit.
+ *
+ * A runner whose working set genuinely does not fit declares its own number in its manifest
+ * (`execution.maxOldSpaceMb`) — the number belongs next to the addon that knows its working set.
+ * `stream-broker` (1323 MB measured, frame buffers) is the one shipped addon that does.
+ */
+export declare const HEAVY_MAX_OLD_MB_DEFAULT = 1024;
 interface SpawnedProcess {
     readonly pid: number;
     readonly nodeId: string;

package/dist/logging/log-manager.d.ts

@@ -54,11 +54,13 @@ export declare class LogManager {
      * `perAddonCapacity` bounds EACH addon's bucket, not the total — a chatty addon
      * evicts only its own lines, so quiet addons keep their sparse history.
      *
-     * `options.maxTotalEntries` adds a soft ceiling across all buckets, because the
-     * per-bucket bound scales with addon count. When it is exceeded, only entries at
-     * or below `options.pruneLevel` (default `debug`) are discarded — `warn` and
-     * `error` are never evicted to satisfy it. Both default to the previous
-     * behaviour: no total cap. See {@link PartitionedLogBuffer}.
+     * `options.maxTotalEntries` ceilings the total across all buckets, because the
+     * per-bucket bound scales with addon count, and `options.maxBuckets` ceilings the
+     * bucket count itself. When the total is exceeded, entries at or below
+     * `options.pruneLevel` (default `debug`) are discarded first — a live addon's
+     * `warn`/`error` are never evicted to satisfy it — and only if that cannot reach
+     * the target are whole least-recently-written buckets dropped. Both bounds are ON
+     * by default; pass an explicit `null` to opt out. See {@link PartitionedLogBuffer}.
      */
     constructor(perAddonCapacity?: number, options?: PartitionedLogBufferOptions);
     /** Entries currently retained across every bucket. */