@camstack/system 1.2.63 → 1.2.65

package/dist/builtins/sqlite-storage/vector-index-vec.d.ts

@@ -12,6 +12,25 @@ export interface RawSqliteDatabase {
     };
     loadExtension?(path: string): void;
 }
+/**
+ * The largest `k` sqlite-vec will accept in a KNN query.
+ *
+ * This is the EXTENSION's own compile-time limit, not a number chosen here —
+ * measured against the real extension, which answers a larger `k` with
+ * `SqliteError: k value in knn query too large, provided 20000 and the limit
+ * is 4096` rather than with rows.
+ *
+ * It matters that this is the extension's number. The vector door looked like
+ * a bypass of {@link SETTINGS_QUERY_HARD_ROW_CAP}: `vector-store.cap.ts`
+ * declares `topK: z.number().int().positive()` with no `.max()`, and it is
+ * bound straight into `k = ?` on the same connection, in the same process, as
+ * the capped `data-store-provider.query`. It is not a bypass — sqlite-vec was
+ * holding the line the whole time, which caps a KNN's heap cost at 4 096 rows
+ * of metadata. What was actually broken is that it held the line by THROWING,
+ * so an over-large `topK` reached the caller as a raw SQLite error instead of
+ * as the bounded answer it could always have been served.
+ */
+export declare const VEC_KNN_MAX_K = 4096;
 export interface SqliteVecIndexDeps {
     readonly db: RawSqliteDatabase;
     readonly logger: IScopedLogger;

package/dist/builtins/storage-orchestrator/storage-orchestrator.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-LDrOFrd-.js");
+const require_dist = require("../../dist-CIkGOAcz.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
 let node_fs_promises = require("node:fs/promises");

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { dt as BaseAddon, it as storageCapability, jt as parseJsonObject, nt as settingsStoreCapability, p as StorageLocationTypeSchema } from "../../dist-BJ2w3uoN.mjs";
+import { dt as BaseAddon, it as storageCapability, jt as parseJsonObject, nt as settingsStoreCapability, p as StorageLocationTypeSchema } from "../../dist-DqPyKwVB.mjs";
 import * as path$1 from "node:path";
 import * as fs from "node:fs/promises";
 import { buildStorageLocationRegistry } from "@camstack/system";

package/dist/builtins/system-config/system-config.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-LDrOFrd-.js");
+const require_dist = require("../../dist-CIkGOAcz.js");
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,4 +1,4 @@
-import { Ot as hydrateSchema, dt as BaseAddon, ut as errMsg } from "../../dist-BJ2w3uoN.mjs";
+import { Ot as hydrateSchema, dt as BaseAddon, ut as errMsg } from "../../dist-DqPyKwVB.mjs";
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/winston-logging/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-LDrOFrd-.js");
+const require_dist = require("../../dist-CIkGOAcz.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/builtins/winston-logging/index.mjs

@@ -1,4 +1,4 @@
-import { G as logDestinationCapability, dt as BaseAddon } from "../../dist-BJ2w3uoN.mjs";
+import { G as logDestinationCapability, dt as BaseAddon } from "../../dist-DqPyKwVB.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 import * as path$1 from "node:path";
 import path from "node:path";

package/dist/{dist-LDrOFrd-.js → dist-CIkGOAcz.js}

@@ -15278,6 +15278,43 @@ var CameraRecordingStatusSchema = zod.z.object({
 	storageBytes: zod.z.number()
 });
 /**
+* The stages of the status fan-out that issue a BOUNDED remote read, and can
+* therefore be cut short. Every other block (`assignment`, `decoder`, `motion`,
+* `audio`) is composed from orchestrator-local state and cannot time out.
+*
+* `switches` is the operator's per-camera function switches — the read behind
+* `switchedOff`, not a block of its own.
+*/
+var CameraStatusStageSchema = zod.z.enum([
+	"source",
+	"broker",
+	"detection",
+	"recording",
+	"switches"
+]);
+/**
+* WHY a stage could not be trusted.
+*
+* - `timeout` — the stage never answered and the whole status call paid the
+*   full per-stage bound for it. This is the one that used to be invisible.
+* - `error` — the source answered with a rejection.
+* - `partial` — the stage RETURNED, but from an incomplete set of sources: its
+*   value is a floor, not a total. `switchedOff` derived from a partial switch
+*   read can be empty while the operator has switches off.
+*/
+var CameraStatusDegradationReasonSchema = zod.z.enum([
+	"timeout",
+	"error",
+	"partial"
+]);
+/** One stage of the fan-out that could NOT be read, and how long it cost. */
+var CameraStatusDegradationSchema = zod.z.object({
+	stage: CameraStatusStageSchema,
+	reason: CameraStatusDegradationReasonSchema,
+	/** Wall-clock ms spent on the stage before it was abandoned. */
+	elapsedMs: zod.z.number()
+});
+/**
 * Aggregated per-camera pipeline status — server-composed, single call.
 *
 * The `assignment` and `source` blocks are always present.
@@ -15307,9 +15344,28 @@ var CameraStatusSchema = zod.z.object({
 	* differently — a quiet camera that looks identical to a dead one is the
 	* silence-reads-as-never-happened trap this repo keeps paying for.
 	*
-	* Empty when nothing is off. Never contains a switch no provider offers.
+	* Empty when nothing is off, and never contains a switch no provider offers
+	* — but an empty list is only a POSITIVE claim when `degraded` does not name
+	* `'switches'`. When it does, the switch set could not be read and nothing
+	* here may be rendered as "the operator turned nothing off": that is the
+	* D62 failure (a camera we could not read painted as broken) in the very
+	* field that exists to prevent it.
 	*/
 	switchedOff: zod.z.array(CameraSwitchIdSchema).readonly(),
+	/**
+	* Stages of the bounded fan-out that were CUT SHORT — a timeout or a
+	* rejection — and whose block is therefore `null` because we could not
+	* READ it, not because there is nothing there.
+	*
+	* Without this, three different facts arrive as the same `null`: "the stage
+	* timed out", "the stage failed", and "this camera legitimately has no
+	* decoder / no recording". Every surface that draws a conclusion from a null
+	* block (or from an empty `switchedOff`) must consult this first; a stage
+	* named here supports no conclusion at all, only "unknown".
+	*
+	* Empty on a clean read — the overwhelmingly common case.
+	*/
+	degraded: zod.z.array(CameraStatusDegradationSchema).readonly(),
 	/** Unix timestamp (ms) when this snapshot was composed server-side. */
 	fetchedAt: zod.z.number()
 });
@@ -19525,7 +19581,29 @@ var FaceInfoSchema = zod.z.object({
 	recognizedIdentityId: zod.z.string().optional(),
 	identityName: zod.z.string().optional(),
 	assigned: zod.z.boolean(),
+	/**
+	* The crop, inline, base64.
+	*
+	* **Prefer {@link cropUrl}.** At the 500 rows the Faces view asks for this
+	* field alone is ~2.87 MiB, re-sent in full on every operator assign and
+	* every 30 s poll, base64-inflated over the msgpack socket and held in the
+	* query heap. It stays for callers that have not migrated; `includeCrops:
+	* false` turns it off once they have.
+	*/
 	base64: zod.z.string().optional(),
+	/**
+	* Same crop, as a data-plane URL for `<img src>` — the move the admin
+	* snapshot surfaces made on 2026-08-08.
+	*
+	* Served by the `event-media` plane, which resolves a raw MediaStore key and
+	* is `access: 'authenticated'`: a bare `<img>` carries the `camstack_session`
+	* cookie, so no header plumbing is needed. The bytes then ride the browser's
+	* HTTP cache with an ETag and `immutable`, instead of the WebSocket.
+	*
+	* Absent when the face has no stored crop, or when the addon has no data
+	* plane — callers fall back to {@link base64}.
+	*/
+	cropUrl: zod.z.string().optional(),
 	/** Design B: the face bbox (pixel space) on the key frame — lets a detail
 	*  view draw the box over the native `keyFrameMediaKey` frame. Absent on
 	*  legacy rows written before design B. */
@@ -19601,7 +19679,23 @@ var faceGalleryCapability = {
 		}),
 		listRecentFaces: method(zod.z.object({
 			limit: zod.z.number().int().positive().optional(),
-			filter: FaceFilterEnum.optional()
+			filter: FaceFilterEnum.optional(),
+			/**
+			* Inline the base64 crop on every row. Default `true` — the existing
+			* behaviour, kept so no caller breaks.
+			*
+			* Set `false` once the caller renders {@link FaceInfo.cropUrl}: that
+			* drops ~2.87 MiB per 500-row page to a few KiB of metadata and lets
+			* the browser cache the images.
+			*
+			* **This is an INPUT field, so it does not reach the addon until the
+			* next train.** The hub router validates cap inputs against its own
+			* compiled Zod, which strips a key it does not know — verified today
+			* on the OUTPUT side, where an additive field DOES arrive immediately
+			* (`Track.hasFace`). Until the train ships, sending `false` is
+			* harmless and simply keeps the crops inline.
+			*/
+			includeCrops: zod.z.boolean().optional()
 		}).optional(), zod.z.array(FaceInfoSchema).readonly()),
 		getFaceByTrack: method(zod.z.object({
 			deviceId: zod.z.number().int(),

package/dist/{dist-BJ2w3uoN.mjs → dist-DqPyKwVB.mjs}

@@ -15278,6 +15278,43 @@ var CameraRecordingStatusSchema = z.object({
 	storageBytes: z.number()
 });
 /**
+* The stages of the status fan-out that issue a BOUNDED remote read, and can
+* therefore be cut short. Every other block (`assignment`, `decoder`, `motion`,
+* `audio`) is composed from orchestrator-local state and cannot time out.
+*
+* `switches` is the operator's per-camera function switches — the read behind
+* `switchedOff`, not a block of its own.
+*/
+var CameraStatusStageSchema = z.enum([
+	"source",
+	"broker",
+	"detection",
+	"recording",
+	"switches"
+]);
+/**
+* WHY a stage could not be trusted.
+*
+* - `timeout` — the stage never answered and the whole status call paid the
+*   full per-stage bound for it. This is the one that used to be invisible.
+* - `error` — the source answered with a rejection.
+* - `partial` — the stage RETURNED, but from an incomplete set of sources: its
+*   value is a floor, not a total. `switchedOff` derived from a partial switch
+*   read can be empty while the operator has switches off.
+*/
+var CameraStatusDegradationReasonSchema = z.enum([
+	"timeout",
+	"error",
+	"partial"
+]);
+/** One stage of the fan-out that could NOT be read, and how long it cost. */
+var CameraStatusDegradationSchema = z.object({
+	stage: CameraStatusStageSchema,
+	reason: CameraStatusDegradationReasonSchema,
+	/** Wall-clock ms spent on the stage before it was abandoned. */
+	elapsedMs: z.number()
+});
+/**
 * Aggregated per-camera pipeline status — server-composed, single call.
 *
 * The `assignment` and `source` blocks are always present.
@@ -15307,9 +15344,28 @@ var CameraStatusSchema = z.object({
 	* differently — a quiet camera that looks identical to a dead one is the
 	* silence-reads-as-never-happened trap this repo keeps paying for.
 	*
-	* Empty when nothing is off. Never contains a switch no provider offers.
+	* Empty when nothing is off, and never contains a switch no provider offers
+	* — but an empty list is only a POSITIVE claim when `degraded` does not name
+	* `'switches'`. When it does, the switch set could not be read and nothing
+	* here may be rendered as "the operator turned nothing off": that is the
+	* D62 failure (a camera we could not read painted as broken) in the very
+	* field that exists to prevent it.
 	*/
 	switchedOff: z.array(CameraSwitchIdSchema).readonly(),
+	/**
+	* Stages of the bounded fan-out that were CUT SHORT — a timeout or a
+	* rejection — and whose block is therefore `null` because we could not
+	* READ it, not because there is nothing there.
+	*
+	* Without this, three different facts arrive as the same `null`: "the stage
+	* timed out", "the stage failed", and "this camera legitimately has no
+	* decoder / no recording". Every surface that draws a conclusion from a null
+	* block (or from an empty `switchedOff`) must consult this first; a stage
+	* named here supports no conclusion at all, only "unknown".
+	*
+	* Empty on a clean read — the overwhelmingly common case.
+	*/
+	degraded: z.array(CameraStatusDegradationSchema).readonly(),
 	/** Unix timestamp (ms) when this snapshot was composed server-side. */
 	fetchedAt: z.number()
 });
@@ -19525,7 +19581,29 @@ var FaceInfoSchema = z.object({
 	recognizedIdentityId: z.string().optional(),
 	identityName: z.string().optional(),
 	assigned: z.boolean(),
+	/**
+	* The crop, inline, base64.
+	*
+	* **Prefer {@link cropUrl}.** At the 500 rows the Faces view asks for this
+	* field alone is ~2.87 MiB, re-sent in full on every operator assign and
+	* every 30 s poll, base64-inflated over the msgpack socket and held in the
+	* query heap. It stays for callers that have not migrated; `includeCrops:
+	* false` turns it off once they have.
+	*/
 	base64: z.string().optional(),
+	/**
+	* Same crop, as a data-plane URL for `<img src>` — the move the admin
+	* snapshot surfaces made on 2026-08-08.
+	*
+	* Served by the `event-media` plane, which resolves a raw MediaStore key and
+	* is `access: 'authenticated'`: a bare `<img>` carries the `camstack_session`
+	* cookie, so no header plumbing is needed. The bytes then ride the browser's
+	* HTTP cache with an ETag and `immutable`, instead of the WebSocket.
+	*
+	* Absent when the face has no stored crop, or when the addon has no data
+	* plane — callers fall back to {@link base64}.
+	*/
+	cropUrl: z.string().optional(),
 	/** Design B: the face bbox (pixel space) on the key frame — lets a detail
 	*  view draw the box over the native `keyFrameMediaKey` frame. Absent on
 	*  legacy rows written before design B. */
@@ -19601,7 +19679,23 @@ var faceGalleryCapability = {
 		}),
 		listRecentFaces: method(z.object({
 			limit: z.number().int().positive().optional(),
-			filter: FaceFilterEnum.optional()
+			filter: FaceFilterEnum.optional(),
+			/**
+			* Inline the base64 crop on every row. Default `true` — the existing
+			* behaviour, kept so no caller breaks.
+			*
+			* Set `false` once the caller renders {@link FaceInfo.cropUrl}: that
+			* drops ~2.87 MiB per 500-row page to a few KiB of metadata and lets
+			* the browser cache the images.
+			*
+			* **This is an INPUT field, so it does not reach the addon until the
+			* next train.** The hub router validates cap inputs against its own
+			* compiled Zod, which strips a key it does not know — verified today
+			* on the OUTPUT side, where an additive field DOES arrive immediately
+			* (`Track.hasFace`). Until the train ships, sending `false` is
+			* harmless and simply keeps the crops inline.
+			*/
+			includeCrops: z.boolean().optional()
 		}).optional(), z.array(FaceInfoSchema).readonly()),
 		getFaceByTrack: method(z.object({
 			deviceId: z.number().int(),

package/dist/http/asset-compression.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Content-coding for addon-served static assets: `Accept-Encoding` negotiation,
+ * an eligibility rule, and a BOUNDED cache of the compressed bytes.
+ *
+ * ## Why the ADDON owns the encoding
+ *
+ * The hub's `/addon/:addonId/*` bridge is registered `{ compress: false }`. That
+ * is not an oversight — on 2026-07-16 the global `@fastify/compress` was found
+ * emitting an EMPTY brotli stream (`content-encoding: br`, `content-length: 0`)
+ * for any compressible body over its 1 KiB threshold once the body had crossed
+ * the UDS route bridge of a FORKED addon. It silently broke the notifier SVG
+ * icons; the deploy-bundle pull route had already dodged the same class with
+ * `compress: false`. The resolution then, and the contract now, is that an addon
+ * route owns its content-coding END TO END: it negotiates, it compresses, it
+ * stamps `content-encoding` + `Vary`, and the hub pipes those bytes through
+ * untouched (`proxyToUpstream` replays the upstream headers verbatim).
+ *
+ * So compression belongs HERE, in the shared file data-plane, and nowhere above
+ * it. Anything that re-compresses on top of this reintroduces the empty-brotli
+ * bug rather than doubling the ratio.
+ *
+ * ## Why the bytes are cached, and why the cache is bounded
+ *
+ * Measured on the stream-broker embed bundle (`index-<hash>.js`, 1,443,142 B):
+ * gzip-6 → 360,868 B, brotli-5 → 327,419 B in 27 ms, brotli-11 → 293,677 B in
+ * 2,233 ms. Quality 5 is the request-path choice: 77% off the wire for 27 ms
+ * paid ONCE. Quality 11 buys another 2.3% for eighty times the CPU, on a path
+ * where a real client is waiting.
+ *
+ * The cache is an LRU bounded by BOTH entry count and total bytes, and it
+ * refuses assets over {@link COMPRESSION_MAX_ASSET_BYTES} outright. An unbounded
+ * `Map` keyed by URL is how a long-lived process walks into an OOM, and this
+ * repo has already spent a session on one.
+ *
+ * The key carries `mtimeMs` and `size`, so a rebuild that rewrites an asset in
+ * place under an UNCHANGED name (an SPA shell, a service worker) can never be
+ * served from the previous build's bytes.
+ */
+/** The codings this layer will produce. Identity is the absence of one. */
+export type ContentEncoding = 'br' | 'gzip';
+/**
+ * Below this the framing and the `Vary` cache split cost more than the
+ * compression saves. Same threshold the hub's global compressor is registered
+ * with, deliberately.
+ */
+export declare const COMPRESSION_MIN_BYTES = 1024;
+/**
+ * Above this an asset is streamed identity and never buffered. Compression
+ * requires the whole body in RAM twice; a multi-hundred-MB recording segment
+ * must not be able to do that, whatever its content type says.
+ */
+export declare const COMPRESSION_MAX_ASSET_BYTES: number;
+/** Is a body of this content type worth compressing at all? */
+export declare function isCompressibleContentType(contentType: string): boolean;
+/**
+ * Pick a coding for this request: brotli when offered, else gzip, else identity.
+ *
+ * Returns `null` for identity — including when the header is ABSENT. A client
+ * that offers nothing gets the raw bytes; guessing on its behalf is how a
+ * non-negotiating consumer (a native fetch, a probe, an OTA puller) ends up with
+ * a body it cannot read.
+ */
+export declare function negotiateContentEncoding(acceptEncoding: string | undefined): ContentEncoding | null;
+/** Identity of one compressed body. `mtimeMs`+`size` make a rebuild-in-place a MISS. */
+export interface CompressedAssetKey {
+    readonly path: string;
+    readonly mtimeMs: number;
+    readonly size: number;
+    readonly encoding: ContentEncoding;
+}
+/** Counters for the cache. Exported so a test can prove the compressor ran ONCE. */
+export interface AssetCompressionStats {
+    /** Bodies actually run through zlib. */
+    readonly compressions: number;
+    /** Requests served from already-compressed bytes. */
+    readonly hits: number;
+    readonly entries: number;
+    readonly bytes: number;
+}
+/**
+ * Compressed bytes for one asset, compressing at most once per key.
+ *
+ * `null` means "send the original" — the asset is too large to buffer, the
+ * source could not be read, or compression did not actually shrink it. Every
+ * failure degrades to identity, so this can only ever be an optimisation.
+ *
+ * Concurrent callers for the same key share ONE compression: a cold cache hit by
+ * a dozen parallel asset requests must not run zlib a dozen times.
+ */
+export declare function getCompressedAsset(key: CompressedAssetKey, readSource: () => Promise<Buffer>): Promise<Buffer | null>;
+export declare function getAssetCompressionStats(): AssetCompressionStats;
+/** Test seam — the cache and its counters are process-wide. */
+export declare function resetAssetCompressionCache(): void;

package/dist/index.js

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-LDrOFrd-.js");
-const require_model_download_service = require("./model-download-service-Cpc6SWzV.js");
-const require_manifest_python_deps = require("./manifest-python-deps-DNfmBu20.js");
+const require_dist = require("./dist-CIkGOAcz.js");
+const require_model_download_service = require("./model-download-service-Caj1kaSi.js");
+const require_manifest_python_deps = require("./manifest-python-deps-BE6l8Y4W.js");
 const require_resource_monitor = require("./resource-monitor-DNNomR-i.js");
 const require_builtins_sqlite_storage_filesystem_storage_addon = require("./builtins/sqlite-storage/filesystem-storage.addon.js");
 const require_builtins_sqlite_storage_sqlite_settings_addon = require("./builtins/sqlite-storage/sqlite-settings.addon.js");
@@ -41,10 +41,10 @@ let node_fs$1 = require_chunk.__toESM(node_fs, 1);
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path, 1);
-let _camstack_types_addon = require("@camstack/types/addon");
-let node_child_process = require("node:child_process");
 let node_util = require("node:util");
 node_util = require_chunk.__toESM(node_util);
+let _camstack_types_addon = require("@camstack/types/addon");
+let node_child_process = require("node:child_process");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_fs_promises = require("node:fs/promises");
@@ -139,6 +139,30 @@ var HEAP_WATCH_INTERVAL_MS = 6e4;
 *  the fatal by more than one interval under realistic growth. */
 var HEAP_WATCH_WARN_RATIO = .8;
 /**
+* Escalate above this share of the ceiling.
+*
+* 0.70 is 3002MB: clear of the measured routine max (2847MB) so steady state
+* never escalates, and below {@link HEAP_WATCH_WARN_RATIO} so the fast cadence
+* is already running by the time the warn is reachable.
+*/
+var HEAP_WATCH_ESCALATE_RATIO = .7;
+/**
+* Release escalation below this share.
+*
+* Hysteresis, not a second threshold: hub-main's heap sawtooths continuously,
+* so a single ratio would flap the mode on every GC. 0.60 is 2573MB — a real
+* retreat rather than the trough of one collection.
+*/
+var HEAP_WATCH_DEESCALATE_RATIO = .6;
+/**
+* The cadence state machine, pure so the thresholds are testable without
+* allocating three gigabytes to reach them.
+*/
+function nextMode(current, usedRatio, escalateRatio = HEAP_WATCH_ESCALATE_RATIO, deescalateRatio = HEAP_WATCH_DEESCALATE_RATIO) {
+	if (current === "escalated") return usedRatio < deescalateRatio ? "steady" : "escalated";
+	return usedRatio >= escalateRatio ? "escalated" : "steady";
+}
+/**
 * Reclaim once the process holds this many MB beyond what it is USING.
 *
 * Live calibration, both readings from the same hub minutes apart: 2491MB
@@ -229,6 +253,9 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 	const now = reclaimOptions?.now ?? (() => Date.now());
 	const triggerMb = reclaimOptions?.triggerMb ?? 1536;
 	const minIntervalMs = reclaimOptions?.minIntervalMs ?? 6e5;
+	const fastIntervalMs = reclaimOptions?.fastIntervalMs ?? 2e3;
+	const escalateRatio = reclaimOptions?.escalateRatio ?? .7;
+	const deescalateRatio = reclaimOptions?.deescalateRatio ?? .6;
 	let lastReclaimAt = Number.NEGATIVE_INFINITY;
 	const read = () => {
 		const limit = reclaimOptions?.heapLimitBytes ?? node_v8.getHeapStatistics().heap_size_limit;
@@ -249,16 +276,43 @@ function startHeapWatch(label = "hub-main", sink = consoleSink, intervalMs = HEA
 		const after = read();
 		sink.info(`[mem] reclaim ${label} stranded=${strandedMb(sample)}MB rss=${sample.rssMb}MB→${after.rssMb}MB freed=${sample.rssMb - after.rssMb}MB arrayBuffers=${sample.arrayBuffersMb}MB→${after.arrayBuffersMb}MB took=${now() - startedAt}ms`);
 	};
+	let mode = "steady";
+	let lastLoggedAt = Number.NEGATIVE_INFINITY;
+	/**
+	* PROBING and LOGGING are separate cadences, and that separation is the whole
+	* point.
+	*
+	* The 2026-08-08 fatal escaped a 60s heartbeat because the burst began and
+	* ended between two samples. Deciding "is the heap elevated?" only when a
+	* line is due would reproduce that exactly: the process would still be read
+	* once a minute, and a 62-second climb would still be invisible. So the timer
+	* runs at the FAST period always — `process.memoryUsage()` is tens of
+	* microseconds, i.e. free at this rate — and the slow period governs only how
+	* often a steady process is allowed to say so.
+	*
+	* Never probe slower than the log cadence, or a caller passing a short
+	* `intervalMs` would silently get the long one.
+	*/
+	const probeIntervalMs = Math.min(fastIntervalMs, intervalMs);
 	const tick = () => {
 		try {
 			const sample = read();
-			const line = format$1(label, sample);
-			if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
-			else sink.info(line);
+			const previous = mode;
+			mode = nextMode(previous, sample.usedRatio, escalateRatio, deescalateRatio);
+			const at = now();
+			const due = at - lastLoggedAt >= intervalMs;
+			if (mode === "escalated" || due) {
+				lastLoggedAt = at;
+				const line = format$1(label, sample);
+				if (sample.nearLimit) sink.warn(`${line} — APPROACHING HEAP LIMIT`);
+				else if (mode === "escalated") sink.warn(`${line} — heap elevated, sampling every ${probeIntervalMs}ms`);
+				else sink.info(line);
+			}
+			if (previous === "escalated" && mode === "steady") sink.info(`[mem] ${label} heap back to routine — logging every ${intervalMs}ms`);
 			maybeReclaim(sample);
 		} catch {}
 	};
-	const timer = setInterval(tick, intervalMs);
+	const timer = setInterval(tick, probeIntervalMs);
 	timer.unref?.();
 	tick();
 	let stopped = false;