@openclaw/diagnostics-prometheus 2026.11.3 → 2026.11.5-beta.2

package/dist/index.js

@@ -4,6 +4,7 @@ import { isDiagnosticsEnabled, normalizeDiagnosticLane, normalizeDiagnosticValue
 import { asNonNegativeFiniteNumber } from "openclaw/plugin-sdk/number-runtime";
 import { getPluginRuntimeGatewayRequestScope } from "openclaw/plugin-sdk/plugin-runtime";
 import { truncateUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime";
+import { expectDefined } from "openclaw/plugin-sdk/expect-runtime";
 //#region extensions/diagnostics-prometheus/src/prometheus-format.ts
 function sortedLabels(labels) {
 	const entries = Object.entries(labels);
@@ -33,7 +34,167 @@ function seconds(ms) {
 	return value === void 0 ? void 0 : value / 1e3;
 }
 //#endregion
+//#region extensions/diagnostics-prometheus/src/prometheus-family-budget.ts
+const PROMETHEUS_FAMILY_RESERVES = {
+	openclaw_chat_history_requests_total: 4,
+	openclaw_chat_history_response_bytes_total: 4,
+	openclaw_chat_send_phase_seconds: 32,
+	openclaw_child_process_spawn_total: 4,
+	openclaw_code_mode_worker_heap_bytes: 128,
+	openclaw_code_mode_worker_memory_bytes: 128,
+	openclaw_control_ui_document_duration_seconds: 4,
+	openclaw_cron_list_requests_total: 4,
+	openclaw_diagnostic_async_queue_dropped_total: 4,
+	openclaw_diagnostic_async_queue_length: 4,
+	openclaw_diff_cache_misses_total: 4,
+	openclaw_diff_stage_seconds: 4,
+	openclaw_gateway_active_work: 4,
+	openclaw_gateway_build_info: 4,
+	openclaw_gateway_event_loop_delay_max_seconds: 4,
+	openclaw_gateway_event_loop_observed_seconds_total: 4,
+	openclaw_gateway_http_cancelled_total: 4,
+	openclaw_gateway_main_thread_stall_seconds: 4,
+	openclaw_gateway_main_thread_stalls_dropped_total: 4,
+	openclaw_gateway_rpc_admission_seconds: 256,
+	openclaw_gateway_rpc_client_requests_total: 512,
+	openclaw_gateway_rpc_first_response_seconds: 256,
+	openclaw_gateway_rpc_handler_heap_delta_bytes: 256,
+	openclaw_gateway_rpc_handler_heap_delta_exclusive_total: 256,
+	openclaw_gateway_rpc_handler_seconds: 256,
+	openclaw_gateway_rpc_outcomes_total: 256,
+	openclaw_gateway_rpc_queue_wait_seconds: 256,
+	openclaw_gateway_rpc_requests_total: 256,
+	openclaw_gateway_rpc_response_bytes: 256,
+	openclaw_gateway_rpc_stage_seconds: 256,
+	openclaw_gateway_rpc_stage_thread_cpu_seconds: 256,
+	openclaw_gateway_ws_event_bytes_total: 256,
+	openclaw_gateway_ws_event_frame_bytes: 2048,
+	openclaw_gateway_ws_event_wire_bytes_total: 256,
+	openclaw_gateway_ws_events_total: 256,
+	openclaw_gateway_ws_operator_connections: 4,
+	openclaw_gateway_ws_presence_bytes_total: 4,
+	openclaw_gateway_ws_presence_frames_total: 4,
+	openclaw_gateway_ws_session_event_bytes_total: 256,
+	openclaw_gateway_ws_session_event_frames_total: 256,
+	openclaw_gc_duration_seconds: 384,
+	openclaw_gen_ai_client_token_usage: 128,
+	openclaw_harness_run_duration_seconds: 128,
+	openclaw_harness_run_total: 128,
+	openclaw_heap_old_generation_after_gc_bytes: 128,
+	openclaw_heap_old_generation_after_gc_ratio: 128,
+	openclaw_heap_size_limit_bytes: 128,
+	openclaw_heap_space_bytes: 256,
+	openclaw_heap_used_after_major_gc_bytes: 64,
+	openclaw_heap_used_after_major_gc_timestamp_seconds: 64,
+	openclaw_heap_used_ratio: 128,
+	openclaw_liveness_cpu_core_ratio: 4,
+	openclaw_liveness_event_loop_delay_max_seconds: 4,
+	openclaw_liveness_event_loop_delay_p99_seconds: 4,
+	openclaw_liveness_event_loop_utilization_ratio: 4,
+	openclaw_liveness_sessions: 4,
+	openclaw_liveness_warning_total: 4,
+	openclaw_memory_bytes: 128,
+	openclaw_memory_pressure_total: 4,
+	openclaw_memory_rss_bytes: 4,
+	openclaw_message_delivery_duration_seconds: 4,
+	openclaw_message_delivery_started_total: 4,
+	openclaw_message_delivery_total: 4,
+	openclaw_message_dispatch_completed_total: 4,
+	openclaw_message_dispatch_duration_seconds: 4,
+	openclaw_message_dispatch_started_total: 4,
+	openclaw_message_processed_duration_seconds: 4,
+	openclaw_message_processed_total: 4,
+	openclaw_message_received_total: 4,
+	openclaw_model_call_duration_seconds: 128,
+	openclaw_model_call_total: 128,
+	openclaw_model_cost_usd_total: 128,
+	openclaw_model_failover_total: 128,
+	openclaw_model_tokens_total: 128,
+	openclaw_model_usage_duration_seconds: 128,
+	openclaw_models_list_requests_total: 4,
+	openclaw_payload_large_bytes: 4,
+	openclaw_payload_large_total: 4,
+	openclaw_process_anonymous_memory_bytes: 4,
+	openclaw_queue_lane_size: 4,
+	openclaw_queue_lane_wait_seconds: 4,
+	openclaw_run_completed_total: 128,
+	openclaw_run_duration_seconds: 128,
+	openclaw_secret_egress_requests_total: 4,
+	openclaw_session_event_rows_reset_total: 4,
+	openclaw_session_event_rows_retained_bytes: 4,
+	openclaw_session_event_rows_retained_entries: 4,
+	openclaw_session_queue_depth: 4,
+	openclaw_session_recovery_age_seconds: 4,
+	openclaw_session_recovery_total: 4,
+	openclaw_session_row_selection_resets_total: 4,
+	openclaw_session_row_partition_cache_total: 32,
+	openclaw_session_row_partition_revisions_total: 8,
+	openclaw_session_row_selection_rows_total: 64,
+	openclaw_session_row_selections_total: 64,
+	openclaw_session_state_total: 4,
+	openclaw_session_stuck_age_seconds: 4,
+	openclaw_session_stuck_total: 4,
+	openclaw_session_turn_created_total: 4,
+	openclaw_sessions_active: 4,
+	openclaw_sessions_list_base_misses_total: 4,
+	openclaw_sessions_list_baseline_retirements_total: 4,
+	openclaw_sessions_list_requests_total: 4,
+	openclaw_sessions_list_response_bytes_total: 4,
+	openclaw_sessions_list_retained_bytes: 4,
+	openclaw_sessions_list_retained_refs: 4,
+	openclaw_sessions_list_retained_views: 4,
+	openclaw_skill_used_total: 4,
+	openclaw_talk_audio_bytes: 4,
+	openclaw_talk_event_duration_seconds: 4,
+	openclaw_talk_event_total: 4,
+	openclaw_telemetry_exporter_total: 4,
+	openclaw_tool_catalog_tools_total: 128,
+	openclaw_tool_catalog_total: 128,
+	openclaw_tool_execution_blocked_total: 128,
+	openclaw_tool_execution_duration_seconds: 128,
+	openclaw_tool_execution_total: 128,
+	openclaw_webhook_duration_seconds: 4,
+	openclaw_webhook_error_total: 4,
+	openclaw_webhook_received_total: 4,
+	openclaw_worker_array_buffers_bytes: 128,
+	openclaw_worker_count: 128,
+	openclaw_worker_external_bytes: 128,
+	openclaw_worker_gc_collections_total: 128,
+	openclaw_worker_gc_duration_seconds_total: 128,
+	openclaw_worker_gc_reclaimed_bytes_total: 128,
+	openclaw_worker_heap_sampled_count: 128,
+	openclaw_worker_heap_space_used_bytes: 640,
+	openclaw_worker_heap_used_bytes: 128,
+	openclaw_worker_heap_used_high_water_bytes: 128,
+	openclaw_worker_message_payload_bytes_total: 512,
+	openclaw_worker_message_unmeasured_total: 64,
+	openclaw_worker_messages_total: 64,
+	openclaw_worker_queue_depth: 512,
+	openclaw_worker_queue_wait_seconds: 512,
+	openclaw_worker_request_phase_seconds: 1024,
+	openclaw_worker_request_seconds: 512,
+	openclaw_worker_retired_total: 64,
+	openclaw_worker_started_total: 64,
+	openclaw_worker_tasks_completed_total: 128,
+	openclaw_worktree_preparation_seconds: 32
+};
+const SHARED_PROMETHEUS_SERIES = 16384 - Object.values(PROMETHEUS_FAMILY_RESERVES).reduce((sum, n) => sum + n, 0);
+//#endregion
 //#region extensions/diagnostics-prometheus/src/prometheus-metric-store.ts
+function createSeries() {
+	return {
+		samples: [],
+		shapes: /* @__PURE__ */ new Map(),
+		sorted: true
+	};
+}
+function sortedSamples(series) {
+	if (!series.sorted) {
+		series.samples.sort((left, right) => left.key.localeCompare(right.key));
+		series.sorted = true;
+	}
+	return series.samples;
+}
 const DURATION_BUCKETS_SECONDS = [
 	.005,
 	.01,
@@ -58,101 +219,270 @@ const AGENT_DURATION_BUCKETS_SECONDS = [
 	1800,
 	3600
 ];
-const MAX_PROMETHEUS_SERIES = 2048;
 const DROPPED_SERIES_COUNTER_NAME = "openclaw_prometheus_series_dropped_total";
-function createPrometheusMetricStore() {
-	const counters = /* @__PURE__ */ new Map();
-	const gauges = /* @__PURE__ */ new Map();
-	const histograms = /* @__PURE__ */ new Map();
+const DROPPED_FAMILY_COUNTER_NAME = "openclaw_prometheus_family_series_dropped_total";
+const warnedFamilies = /* @__PURE__ */ new Set();
+function createPrometheusMetricStore(onSeriesDropped) {
+	const counters = createSeries();
+	const gauges = createSeries();
+	const histograms = createSeries();
 	let droppedSeries = 0;
-	const canCreateSeries = (map, key) => {
-		if (map.has(key)) return true;
-		if (counters.size + gauges.size + histograms.size < MAX_PROMETHEUS_SERIES) return true;
-		droppedSeries += 1;
-		return false;
+	let sharedSeries = 0;
+	const familyCounts = /* @__PURE__ */ new Map();
+	const familyDrops = /* @__PURE__ */ new Map();
+	const headers = /* @__PURE__ */ new Map();
+	let prefixBuffer = Buffer.alloc(0);
+	let prefixOffset = 0;
+	const encodePrefix = (text) => {
+		const bytes = Buffer.byteLength(text);
+		if (bytes > 4096) {
+			const prefix = Buffer.allocUnsafeSlow(bytes);
+			prefix.write(text);
+			return prefix;
+		}
+		if (prefixOffset + bytes > prefixBuffer.length) {
+			prefixBuffer = Buffer.allocUnsafeSlow(4096);
+			prefixOffset = 0;
+		}
+		const start = prefixOffset;
+		prefixOffset += prefixBuffer.write(text, prefixOffset);
+		return prefixBuffer.subarray(start, prefixOffset);
 	};
-	const counter = (name, help, labels, amount = 1) => {
-		if (!Number.isFinite(amount) || amount <= 0) return;
-		const key = metricKey(name, labels);
-		if (!canCreateSeries(counters, key)) return;
-		const existing = counters.get(key);
-		if (existing) {
-			existing.value += amount;
+	let scratch = Buffer.alloc(0);
+	const series = (map, name, labels) => {
+		let labelCount = 0;
+		for (const key in labels) if (Object.hasOwn(labels, key)) labelCount++;
+		let shape;
+		shapes: for (const candidate of map.shapes.get(name) ?? []) {
+			if (candidate.keys.length !== labelCount) continue;
+			let node = candidate.root;
+			for (const key of candidate.keys) {
+				const value = labels[key];
+				if (value === void 0 || !Object.prototype.propertyIsEnumerable.call(labels, key)) continue shapes;
+				node = node?.values?.get(value);
+			}
+			shape = candidate;
+			if (node?.sample) return node;
+			break;
+		}
+		const count = familyCounts.get(name) ?? 0;
+		const reserve = PROMETHEUS_FAMILY_RESERVES[name];
+		if (count >= Math.max(128, reserve) || count >= reserve && sharedSeries >= SHARED_PROMETHEUS_SERIES) {
+			droppedSeries++;
+			familyDrops.set(name, (familyDrops.get(name) ?? 0) + 1);
+			if (onSeriesDropped && !warnedFamilies.has(name)) {
+				warnedFamilies.add(name);
+				onSeriesDropped(name);
+			}
 			return;
 		}
-		counters.set(key, {
-			help,
-			labels,
-			value: amount
-		});
-	};
-	const gauge = (name, help, labels, value) => {
-		if (value === void 0 || !Number.isFinite(value)) return;
-		const key = metricKey(name, labels);
-		if (!canCreateSeries(gauges, key)) return;
-		gauges.set(key, {
-			help,
-			labels,
-			value
-		});
+		familyCounts.set(name, count + 1);
+		if (count >= reserve) sharedSeries++;
+		if (!shape) {
+			shape = {
+				keys: Object.keys(labels).toSorted((left, right) => left.localeCompare(right)),
+				root: {}
+			};
+			const shapes = map.shapes.get(name);
+			if (shapes) shapes.push(shape);
+			else map.shapes.set(name, [shape]);
+		}
+		let node = shape.root;
+		for (const key of shape.keys) {
+			const value = expectDefined(labels[key], "Prometheus label");
+			const values = node.values ??= /* @__PURE__ */ new Map();
+			let child = values.get(value);
+			if (!child) {
+				child = {};
+				values.set(value, child);
+			}
+			node = child;
+		}
+		return node;
 	};
-	const counterValue = (name, help, labels, value) => {
-		if (!Number.isFinite(value) || value < 0) return;
-		const key = metricKey(name, labels);
-		if (canCreateSeries(counters, key)) counters.set(key, {
-			help,
-			labels,
-			value: Math.max(counters.get(key)?.value ?? 0, value)
-		});
+	const scalar = (map, name, help, labels, value, mode) => {
+		if (value === void 0 || !Number.isFinite(value) || mode !== "set" && value < 0 || mode === "add" && value === 0) return;
+		const node = series(map, name, labels);
+		if (!node) return;
+		if (node.sample) {
+			const next = mode === "add" ? node.sample.value + value : mode === "max" ? Math.max(node.sample.value, value) : value;
+			if (next !== node.sample.value) {
+				node.sample.value = next;
+				node.sample.renderedDirty = true;
+			}
+		} else {
+			node.sample = {
+				help,
+				key: metricKey(name, labels),
+				name,
+				prefix: encodePrefix(`${name}${formatLabels(labels)} `),
+				value,
+				renderedDirty: true
+			};
+			map.samples.push(node.sample);
+			map.sorted = false;
+		}
 	};
+	const counter = (name, help, labels, amount = 1) => scalar(counters, name, help, labels, amount, "add");
+	const counterValue = (name, help, labels, value) => scalar(counters, name, help, labels, value, "max");
+	const gauge = (name, help, labels, value) => scalar(gauges, name, help, labels, value, "set");
 	const clearGauges = (name) => {
-		for (const key of gauges.keys()) if (key.startsWith(`${name}|`)) gauges.delete(key);
+		headers.delete(name);
+		const previousLength = gauges.samples.length;
+		gauges.shapes.delete(name);
+		gauges.samples = gauges.samples.filter((sample) => sample.name !== name);
+		const count = familyCounts.get(name) ?? 0;
+		const remaining = count - (previousLength - gauges.samples.length);
+		const reserve = PROMETHEUS_FAMILY_RESERVES[name];
+		sharedSeries -= Math.max(0, count - reserve) - Math.max(0, remaining - reserve);
+		familyCounts.set(name, remaining);
 	};
-	const histogram = (name, help, labels, value, buckets = DURATION_BUCKETS_SECONDS) => {
-		if (value === void 0 || !Number.isFinite(value)) return;
-		const key = metricKey(name, labels);
-		if (!canCreateSeries(histograms, key)) return;
-		let sample = histograms.get(key);
+	const getHistogram = (name, help, labels, buckets = DURATION_BUCKETS_SECONDS) => {
+		const node = series(histograms, name, labels);
+		if (!node) return;
+		let sample = node.sample;
 		if (!sample) {
 			sample = {
 				buckets,
-				bucketPrefixes: [...buckets, "+Inf"].map((le) => `${name}_bucket${formatLabels({
+				bucketPrefixes: [...buckets, "+Inf"].map((le) => encodePrefix(`${name}_bucket${formatLabels({
 					...labels,
 					le: String(le)
-				})} `),
+				})} `)),
 				counts: buckets.map(() => 0),
 				count: 0,
 				help,
-				labels: formatLabels(labels),
-				sum: 0
+				key: metricKey(name, labels),
+				name,
+				sumPrefix: encodePrefix(`${name}_sum${formatLabels(labels)} `),
+				countPrefix: encodePrefix(`${name}_count${formatLabels(labels)} `),
+				sum: 0,
+				renderedDirty: true
 			};
-			histograms.set(key, sample);
+			node.sample = sample;
+			histograms.samples.push(sample);
+			histograms.sorted = false;
 		}
+		return sample;
+	};
+	const reserveHistogram = (name, help, labels) => {
+		getHistogram(name, help, labels);
+	};
+	const histogram = (name, help, labels, value, buckets = DURATION_BUCKETS_SECONDS) => {
+		if (value === void 0 || !Number.isFinite(value)) return;
+		const sample = getHistogram(name, help, labels, buckets);
+		if (!sample) return;
 		sample.count += 1;
 		sample.sum += value;
+		sample.renderedDirty = true;
 		for (let index = 0; index < sample.buckets.length; index += 1) {
 			const bucket = sample.buckets[index];
 			if (bucket !== void 0 && value <= bucket) sample.counts[index] = (sample.counts[index] ?? 0) + 1;
 		}
 	};
-	const snapshot = () => {
-		const counterSnapshot = [...counters];
-		if (droppedSeries > 0) counterSnapshot.push([metricKey(DROPPED_SERIES_COUNTER_NAME, {}), {
-			help: "Prometheus metric series dropped because the exporter series cap was reached.",
-			labels: {},
-			value: droppedSeries
-		}]);
-		return {
-			counters: counterSnapshot,
-			gauges: [...gauges],
-			histograms: [...histograms]
+	const render = () => {
+		let scratchOffset = 0;
+		let totalBytes = 0;
+		const chunks = [];
+		const append = (chunk) => {
+			chunks.push(chunk);
+			totalBytes += chunk.length;
 		};
+		const write = (prefix, value) => {
+			const number = formatPrometheusNumber(value);
+			const required = scratchOffset + prefix.length + number.length + 1;
+			if (required > scratch.length) {
+				const grown = Buffer.allocUnsafeSlow(Math.max(required, scratch.length * 2));
+				grown.set(scratch.subarray(0, scratchOffset));
+				scratch = grown;
+			}
+			scratch.set(prefix, scratchOffset);
+			scratchOffset += prefix.length;
+			scratchOffset += scratch.write(number, scratchOffset, "ascii");
+			scratch[scratchOffset++] = 10;
+		};
+		const finish = (previous) => {
+			const output = previous?.length === scratchOffset ? previous : new Uint8Array(scratchOffset);
+			scratch.copy(output, 0, 0, scratchOffset);
+			scratchOffset = 0;
+			return output;
+		};
+		const emitted = /* @__PURE__ */ new Set();
+		let previousName;
+		const header = (name, type, help) => {
+			if (previousName === name) return;
+			previousName = name;
+			if (!emitted.has(name)) {
+				emitted.add(name);
+				let cached = headers.get(name);
+				if (!cached || cached.type !== type || cached.help !== help) {
+					cached = {
+						type,
+						help,
+						bytes: encodePrefix(`# HELP ${name} ${escapeHelp(help)}\n# TYPE ${name} ${type}\n`)
+					};
+					headers.set(name, cached);
+				}
+				append(cached.bytes);
+			}
+		};
+		for (const [type, map] of [["counter", counters], ["gauge", gauges]]) {
+			for (const sample of sortedSamples(map)) {
+				header(sample.name, type, sample.help);
+				if (!sample.rendered || sample.renderedDirty) {
+					write(sample.prefix, sample.value);
+					sample.rendered = finish(sample.rendered);
+					sample.renderedDirty = false;
+				}
+				append(sample.rendered);
+			}
+			if (type === "counter" && droppedSeries > 0) {
+				header(DROPPED_SERIES_COUNTER_NAME, type, "New-series observations dropped because an exporter series budget was reached.");
+				write(Buffer.from(`${DROPPED_SERIES_COUNTER_NAME} `), droppedSeries);
+				append(finish());
+				header(DROPPED_FAMILY_COUNTER_NAME, type, "New-series observations dropped by bounded metric family.");
+				for (const [family, count] of familyDrops) write(Buffer.from(`${DROPPED_FAMILY_COUNTER_NAME}${formatLabels({ family })} `), count);
+				append(finish());
+			}
+		}
+		for (const sample of sortedSamples(histograms)) {
+			if (sample.count === 0) continue;
+			header(sample.name, "histogram", sample.help);
+			if (!sample.rendered || sample.renderedDirty) {
+				sample.bucketPrefixes.forEach((prefix, bucketIndex) => {
+					write(prefix, sample.counts[bucketIndex] ?? sample.count);
+				});
+				write(sample.sumPrefix, sample.sum);
+				write(sample.countPrefix, sample.count);
+				sample.rendered = finish(sample.rendered);
+				sample.renderedDirty = false;
+			}
+			append(sample.rendered);
+		}
+		const output = Buffer.from(new ArrayBuffer(totalBytes));
+		let offset = 0;
+		for (const chunk of chunks) {
+			output.set(chunk, offset);
+			offset += chunk.length;
+		}
+		return output;
 	};
 	const reset = () => {
-		counters.clear();
-		gauges.clear();
-		histograms.clear();
+		for (const map of [
+			counters,
+			gauges,
+			histograms
+		]) {
+			map.samples.length = 0;
+			map.shapes.clear();
+		}
 		droppedSeries = 0;
+		sharedSeries = 0;
+		familyCounts.clear();
+		familyDrops.clear();
+		headers.clear();
+		scratch = Buffer.alloc(0);
+		prefixBuffer = Buffer.alloc(0);
+		prefixOffset = 0;
 	};
 	return {
 		counter,
@@ -160,31 +490,142 @@ function createPrometheusMetricStore() {
 		gauge,
 		clearGauges,
 		histogram,
+		reserveHistogram,
 		reset,
-		snapshot
+		render
 	};
 }
 //#endregion
-//#region extensions/diagnostics-prometheus/src/service-child-process.ts
-/** Git owners and SQLite session transports carry bounded operation labels. */
-function recordChildProcessSpawn(store, evt) {
-	store.counter("openclaw_child_process_spawn_total", "Successful child launches through the shared spawn and exec owners.", {
-		family: normalizeDiagnosticValue(evt.family),
-		operation: normalizeDiagnosticValue(evt.operation ?? (evt.family === "git" ? "unknown" : "none"))
-	}, asNonNegativeFiniteNumber(evt.count) ?? 0);
+//#region extensions/diagnostics-prometheus/src/service-gateway-ws.ts
+function createGatewayWsMetricsRecorder(store) {
+	const labels = { event: "" };
+	const frameLabels = {
+		event: "",
+		le: ""
+	};
+	const presenceLabels = { mode: "" };
+	const sessionLabels = {
+		event: "",
+		reason: "",
+		delivery: ""
+	};
+	return (event, count, bytes, wireBytes, buckets, bucketLabels, sessionEvent, presenceMode) => {
+		labels.event = frameLabels.event = sessionLabels.event = event;
+		store.counter("openclaw_gateway_ws_events_total", "Outbound Gateway WebSocket event frames accepted by the sender per socket.", labels, count);
+		store.counter("openclaw_gateway_ws_event_bytes_total", "Encoded outbound Gateway WebSocket event bytes before framing or compression per socket.", labels, bytes);
+		if (wireBytes !== void 0) store.counter("openclaw_gateway_ws_event_wire_bytes_total", "Outbound Gateway WebSocket payload bytes after compression per socket, excluding framing.", labels, wireBytes);
+		if (count > 0) {
+			let cumulative = 0;
+			for (let i = 0; i < bucketLabels.length; i++) {
+				cumulative += buckets[i];
+				frameLabels.le = bucketLabels[i];
+				(cumulative === 0 ? store.counterValue : store.counter)("openclaw_gateway_ws_event_frame_bytes", "Cumulative counts of accepted raw Gateway event frames by byte-size upper bound.", frameLabels, cumulative);
+			}
+		}
+		if (presenceMode) {
+			presenceLabels.mode = presenceMode;
+			store.counter("openclaw_gateway_ws_presence_frames_total", "Outbound presence frames accepted by the sender per socket, by delivery mode.", presenceLabels, count);
+			store.counter("openclaw_gateway_ws_presence_bytes_total", "Encoded outbound presence bytes before framing or compression per socket, by delivery mode.", presenceLabels, bytes);
+		}
+		if (sessionEvent) {
+			sessionLabels.reason = sessionEvent.reason;
+			sessionLabels.delivery = sessionEvent.delivery;
+			store.counter("openclaw_gateway_ws_session_event_frames_total", "Outbound session event frames by reason and exact message subscription per socket.", sessionLabels, count);
+			store.counter("openclaw_gateway_ws_session_event_bytes_total", "Encoded outbound session event bytes by reason and exact message subscription per socket.", sessionLabels, bytes);
+		}
+	};
+}
+function recordGatewayWsConnections(store, operators) {
+	store.gauge("openclaw_gateway_ws_operator_connections", "Connected authenticated Gateway operator WebSockets.", {}, operators);
 }
 //#endregion
 //#region extensions/diagnostics-prometheus/src/service-memory.ts
+const WORKER_MEMORY_METRICS = [
+	[
+		"heapUsed",
+		"openclaw_worker_heap_used_bytes",
+		"heap usage"
+	],
+	[
+		"external",
+		"openclaw_worker_external_bytes",
+		"external memory"
+	],
+	[
+		"arrayBuffers",
+		"openclaw_worker_array_buffers_bytes",
+		"ArrayBuffer memory (included in external)"
+	]
+];
+const HEAP_HEADROOM_METRICS = [
+	[
+		"limit",
+		"openclaw_heap_size_limit_bytes",
+		"Smallest live isolate V8 heap limit by thread group."
+	],
+	[
+		"usedRatio",
+		"openclaw_heap_used_ratio",
+		"Largest live isolate used/limit ratio by thread group."
+	],
+	[
+		"oldBytes",
+		"openclaw_heap_old_generation_after_gc_bytes",
+		"Largest live isolate old_space plus large_object_space usage at its last observed major GC."
+	],
+	[
+		"oldRatio",
+		"openclaw_heap_old_generation_after_gc_ratio",
+		"Largest live isolate post-major-GC old-generation/heap-limit ratio by thread group."
+	]
+];
+function collectHeapHeadroom(headroom, used, limit, oldBytes) {
+	if (limit === void 0 || limit <= 0) return;
+	headroom.limit = Math.min(headroom.limit ?? limit, limit);
+	headroom.usedRatio = Math.max(headroom.usedRatio ?? 0, used / limit);
+	if (oldBytes !== void 0) {
+		headroom.oldBytes = Math.max(headroom.oldBytes ?? 0, oldBytes);
+		headroom.oldRatio = Math.max(headroom.oldRatio ?? 0, oldBytes / limit);
+	}
+}
+function recordHeapHeadroom(store, thread, headroom) {
+	for (const [field, name, description] of HEAP_HEADROOM_METRICS) store.gauge(name, description, { thread }, headroom[field]);
+}
 function recordMemorySample(store, memory, byteBuckets) {
+	for (const [, name] of HEAP_HEADROOM_METRICS) store.clearGauges(name);
+	const mainHeadroom = {};
+	collectHeapHeadroom(mainHeadroom, memory.heapUsedBytes, memory.heapSizeLimitBytes, memory.oldGenerationAfterGcBytes);
+	recordHeapHeadroom(store, "main", mainHeadroom);
+	store.clearGauges("openclaw_process_anonymous_memory_bytes");
+	for (const [kind, field] of [["rss", "anonymousRssBytes"], ["swap", "anonymousSwapBytes"]]) store.gauge("openclaw_process_anonymous_memory_bytes", "Latest Linux process anonymous RSS and swap; includes managed heaps and buffers, not allocator totals.", { kind }, asNonNegativeFiniteNumber(memory[field]));
 	for (const message of memory.workerMessages ?? []) {
 		const labels = {
 			kind: message.kind,
 			direction: message.direction
 		};
 		store.counterValue("openclaw_worker_messages_total", "Messages crossing the Gateway main-thread worker boundary.", labels, message.messages);
-		store.counterValue("openclaw_worker_message_payload_bytes_total", "Known worker payload bytes, excluding transport framing and unmeasured object graphs.", labels, message.payloadBytes);
+		for (const [requestClass, bytes] of Object.entries(message.payloadBytesByRequestClass ?? { [message.kind === "sqlite_request" || message.kind === "sqlite_reply" || message.kind === "authority" ? "other" : ""]: message.payloadBytes })) store.counterValue("openclaw_worker_message_payload_bytes_total", "Known worker payload bytes, excluding transport framing and unmeasured object graphs.", requestClass ? {
+			...labels,
+			request_class: requestClass
+		} : labels, bytes);
 		store.counterValue("openclaw_worker_message_unmeasured_total", "Worker messages without a known payload size; these do not contribute to payload bytes.", labels, message.unmeasuredMessages);
 	}
+	for (const selection of memory.sessionRowSelections?.selections ?? []) {
+		const labels = {
+			kind: selection.kind,
+			task: selection.task
+		};
+		store.counterValue("openclaw_session_row_selections_total", "Successful resident session-row selections by query shape and enclosing task.", labels, selection.calls);
+		store.counterValue("openclaw_session_row_selection_rows_total", "Resident session rows returned by selections, before federation and visibility filtering.", labels, selection.rows);
+	}
+	if (memory.sessionRowSelections) {
+		for (const partition of memory.sessionRowSelections.partitions) for (const outcome of ["hits", "misses"]) store.counterValue("openclaw_session_row_partition_cache_total", "Retained session-list partition lookups by outcome and enclosing selection task.", {
+			task: partition.task,
+			outcome: outcome === "hits" ? "hit" : "miss"
+		}, partition[outcome]);
+		for (const revision of memory.sessionRowSelections.partitionRevisions) store.counterValue("openclaw_session_row_partition_revisions_total", "Session-list partition revisions by synchronous internal change scope; excludes initial partitions.", { reason: revision.reason }, revision.changes);
+		store.counterValue("openclaw_session_row_selection_resets_total", "Broad session-row selection invalidations, including topology replacement and disposal.", {}, memory.sessionRowSelections.resets);
+	}
 	for (const worker of memory.workerLifecycle ?? []) {
 		store.counterValue("openclaw_worker_started_total", "Worker isolates created by bounded script basename.", { script: worker.script }, worker.started);
 		for (const { reason, count } of worker.retired) store.counterValue("openclaw_worker_retired_total", "Worker isolates confirmed exited by owner retirement reason.", {
@@ -192,6 +633,23 @@ function recordMemorySample(store, memory, byteBuckets) {
 			reason
 		}, count);
 	}
+	for (const worker of memory.workerTaskMetrics ?? []) {
+		const labels = {
+			worker_class: worker.workerClass,
+			script: worker.script
+		};
+		store.counterValue("openclaw_worker_tasks_completed_total", "Observed terminal task replies from pool workers, including handled failures.", labels, worker.tasksCompleted);
+		store.gauge("openclaw_worker_heap_used_high_water_bytes", "Largest observed pool worker heap usage, retained across worker retirement.", labels, worker.heapUsedHighWaterBytes);
+		for (const gc of worker.gc) {
+			const gcLabels = {
+				...labels,
+				kind: gc.kind
+			};
+			store.counterValue("openclaw_worker_gc_duration_seconds_total", "Observed pool worker garbage collection duration, retained across worker retirement.", gcLabels, gc.durationMs / 1e3);
+			store.counterValue("openclaw_worker_gc_collections_total", "Observed pool worker garbage collections, retained across worker retirement.", gcLabels, gc.count);
+			store.counterValue("openclaw_worker_gc_reclaimed_bytes_total", "Sum of positive heap usage decreases across observed pool worker garbage collections.", gcLabels, gc.reclaimedBytes);
+		}
+	}
 	for (const [kind, field] of [
 		["rss", "rssBytes"],
 		["heap_total", "heapTotalBytes"],
@@ -217,36 +675,54 @@ function recordMemorySample(store, memory, byteBuckets) {
 	}, space[field]);
 	const workers = /* @__PURE__ */ new Map();
 	store.clearGauges("openclaw_code_mode_worker_heap_bytes");
+	store.clearGauges("openclaw_code_mode_worker_memory_bytes");
 	for (const worker of memory.workerHeaps ?? []) {
-		if (worker.workerSlot !== void 0) for (const [kind, value] of [["used", worker.heapUsed], ["limit", worker.heapSizeLimitBytes]]) store.gauge("openclaw_code_mode_worker_heap_bytes", "Latest live Code Mode isolate heap usage and limit by reusable worker slot.", {
-			slot: String(worker.workerSlot),
-			kind
-		}, value);
+		if (worker.workerSlot !== void 0) {
+			for (const [kind, value] of [["used", worker.heapUsed], ["limit", worker.heapSizeLimitBytes]]) store.gauge("openclaw_code_mode_worker_heap_bytes", "Latest live Code Mode isolate heap usage and limit by reusable worker slot.", {
+				slot: String(worker.workerSlot),
+				kind
+			}, value);
+			for (const [kind, value] of [["external", worker.external], ["array_buffers", worker.arrayBuffers]]) store.gauge("openclaw_code_mode_worker_memory_bytes", "Latest live Code Mode isolate external and ArrayBuffer memory (included in external) by reusable worker slot.", {
+				slot: String(worker.workerSlot),
+				kind
+			}, value);
+		}
 		const totals = workers.get(worker.script) ?? {
 			count: 0,
-			sampled: 0,
-			heapUsed: void 0
+			sampled: 0
 		};
 		totals.count++;
 		totals.sampled++;
-		const heapUsed = asNonNegativeFiniteNumber(worker.heapUsed);
-		if (heapUsed !== void 0) totals.heapUsed = (totals.heapUsed ?? 0) + heapUsed;
+		collectHeapHeadroom(totals, worker.heapUsed, worker.heapSizeLimitBytes, worker.oldGenerationAfterGcBytes);
+		for (const [field] of WORKER_MEMORY_METRICS) {
+			const value = worker[field];
+			if (value !== void 0) totals[field] = (totals[field] ?? 0) + value;
+		}
+		for (const space of worker.heapSpaces ?? []) {
+			totals.heapSpaces ??= /* @__PURE__ */ new Map();
+			totals.heapSpaces.set(space.space_name, (totals.heapSpaces.get(space.space_name) ?? 0) + space.space_used_size);
+		}
 		workers.set(worker.script, totals);
 	}
 	for (const worker of memory.workerMemoryMissing ?? []) {
 		const totals = workers.get(worker.script) ?? {
 			count: 0,
-			sampled: 0,
-			heapUsed: void 0
+			sampled: 0
 		};
 		totals.count++;
 		workers.set(worker.script, totals);
 	}
-	store.clearGauges("openclaw_worker_heap_used_bytes");
+	for (const [, name] of WORKER_MEMORY_METRICS) store.clearGauges(name);
+	store.clearGauges("openclaw_worker_heap_space_used_bytes");
 	for (const [script, totals] of workers) {
+		recordHeapHeadroom(store, script, totals);
 		store.gauge("openclaw_worker_count", "Worker isolate counts.", { script }, totals.count);
 		store.gauge("openclaw_worker_heap_sampled_count", "Worker isolate counts.", { script }, totals.sampled);
-		store.gauge("openclaw_worker_heap_used_bytes", "Latest live Worker heap usage by bounded script basename.", { script }, totals.heapUsed);
+		for (const [field, name, description] of WORKER_MEMORY_METRICS) store.gauge(name, `Latest live Worker ${description} by bounded script basename.`, { script }, totals[field]);
+		for (const [space, bytes] of totals.heapSpaces ?? []) store.gauge("openclaw_worker_heap_space_used_bytes", "Latest live Worker V8 heap space usage by bounded script basename.", {
+			script,
+			space
+		}, bytes);
 	}
 	store.histogram("openclaw_memory_rss_bytes", "RSS memory sample distribution in bytes.", {}, asNonNegativeFiniteNumber(memory.rssBytes), byteBuckets);
 }
@@ -297,6 +773,20 @@ function recordModelUsage(store, evt) {
 }
 //#endregion
 //#region extensions/diagnostics-prometheus/src/service-operation-timing.ts
+const GC_DURATION_NAME = "openclaw_gc_duration_seconds";
+const GC_DURATION_HELP = "Elapsed garbage collection duration in seconds by collection kind, callback flags, and isolate role.";
+function reserveMainGcHistograms(store) {
+	for (const kind of [
+		"scavenge",
+		"mark_sweep_compact",
+		"incremental",
+		"weak_processing"
+	]) store.reserveHistogram(GC_DURATION_NAME, GC_DURATION_HELP, {
+		kind,
+		reason: "other",
+		thread: "main"
+	});
+}
 const RPC_DURATION_BUCKETS_SECONDS = [
 	.005,
 	.01,
@@ -341,6 +831,14 @@ const RPC_DURATION_BUCKETS_SECONDS = [
 	600
 ];
 const RESPONSE_BYTE_BUCKETS = Array.from({ length: 17 }, (_, index) => 1024 * 2 ** index);
+const MAIN_THREAD_STALL_BUCKETS_SECONDS = [
+	.25,
+	.5,
+	1,
+	2.5,
+	5,
+	10
+];
 const HEAP_DELTA_BYTE_BUCKETS = [
 	...RESPONSE_BYTE_BUCKETS.toReversed().map((bytes) => -bytes),
 	0,
@@ -356,9 +854,41 @@ const CATALOG_LIST_PHASES = /* @__PURE__ */ new Set([
 	"projection_final",
 	"delivery"
 ]);
+const CHAT_STARTUP_PHASE = /^chat\.startup\.(session_entry|pending_inputs|history_page|startup_projection|projection_final|session_info)$/;
+const DIFF_CACHE_MISS_REASONS = /* @__PURE__ */ new Set([
+	"cold",
+	"evicted",
+	"pending",
+	"no-revision",
+	"no-revision-environment",
+	"no-revision-platform",
+	"no-revision-metadata",
+	"no-revision-git-installation",
+	"no-revision-config",
+	"no-revision-reftable",
+	"no-revision-alternates",
+	"no-revision-symlink",
+	"no-revision-nested-repository",
+	"no-revision-status",
+	"no-revision-unmerged",
+	"no-revision-submodule",
+	"no-revision-permission",
+	"no-revision-missing",
+	"no-revision-io",
+	"oversized",
+	"revision-changed-head",
+	"revision-changed-index",
+	"revision-changed-untracked-set",
+	"revision-changed-worktree-mtime",
+	"revision-changed-metadata"
+]);
 const CHAT_SEND_PHASE = /^chat\.send\.(authority|admission|preparation|attachments|replyContext|authoring|persist|runAdmission|replyInitialization|snapshot|worktree|effects|response|dispatch)$/;
+const CONTROL_UI_DOCUMENT_STAGE = /^control-ui\.document\.(auth_grants|identity_avatar|plugin_catalog|git_branch|preferences|render|total)$/;
 function recordOperationTimingEvent(store, evt, metadata) {
 	switch (evt.type) {
+		case "sessions.list.baseline.retired":
+			if (metadata.trusted) store.counter("openclaw_sessions_list_baseline_retirements_total", "Session list baseline retirement events by cause, not rows or views retired.", { cause: evt.cause });
+			return;
 		case "secret.egress":
 			store.counter("openclaw_secret_egress_requests_total", "Secret egress proxy requests by outcome and credential substitution.", {
 				outcome: evt.outcome,
@@ -378,20 +908,87 @@ function recordOperationTimingEvent(store, evt, metadata) {
 			store.counter("openclaw_gateway_http_cancelled_total", "Gateway HTTP requests cancelled before completion.", { source: evt.source });
 			return;
 		case "diagnostic.gc":
-			store.histogram("openclaw_gc_duration_seconds", "Elapsed garbage collection duration in seconds by collection kind and isolate role.", {
+			if (evt.kind === "mark_sweep_compact") {
+				const labels = { thread: evt.thread ?? "main" };
+				store.gauge("openclaw_heap_used_after_major_gc_bytes", "Native used heap after the latest received major collection by isolate role.", labels, evt.heapUsedAfterMajorGcBytes);
+				store.gauge("openclaw_heap_used_after_major_gc_timestamp_seconds", "Unix observation time of the latest received native major-GC heap sample.", labels, evt.heapUsedAfterMajorGcTimestampSeconds);
+			}
+			store.histogram(GC_DURATION_NAME, GC_DURATION_HELP, {
 				kind: evt.kind ?? "unknown",
+				reason: evt.reason ?? "other",
 				thread: evt.thread ?? "main",
 				...evt.workerSlot === void 0 ? {} : { slot: String(evt.workerSlot) }
 			}, seconds(evt.durationMs));
 			return;
+		case "gateway.main_thread.stall":
+			for (const stall of evt.stalls) store.histogram("openclaw_gateway_main_thread_stall_seconds", "Elapsed main-thread tasks lasting at least 250 milliseconds, by work scope.", { task: normalizeDiagnosticValue(stall.task) }, seconds(stall.durationMs), MAIN_THREAD_STALL_BUCKETS_SECONDS);
+			store.counter("openclaw_gateway_main_thread_stalls_dropped_total", "Main-thread stall records dropped because the attribution buffer was full.", {}, evt.dropped);
+			return;
 		case "gateway.event_loop.sample":
 			store.histogram("openclaw_gateway_event_loop_delay_max_seconds", "Maximum event-loop delay per completed Gateway observation window in seconds.", {}, seconds(evt.delayMaxMs));
 			store.counter("openclaw_gateway_event_loop_observed_seconds_total", "Elapsed seconds covered by completed Gateway event-loop observation windows.", {}, evt.intervalMs / 1e3);
 			return;
 		case "diagnostic.phase.completed": {
 			if (!metadata.trusted) return;
+			const documentStage = CONTROL_UI_DOCUMENT_STAGE.exec(evt.name)?.[1];
+			if (documentStage) {
+				store.histogram("openclaw_control_ui_document_duration_seconds", "Elapsed Control UI HTML document handler stages in seconds; stages can overlap.", { stage: documentStage }, seconds(evt.durationMs));
+				return;
+			}
+			if (evt.name === "sessions.diff" || evt.name === "checkout.diff") {
+				const outcome = evt.details?.outcome;
+				if (outcome !== "cache-hit" && outcome !== "cache-miss") return;
+				const reason = evt.details?.missReason;
+				if (outcome === "cache-miss" && typeof reason === "string" && DIFF_CACHE_MISS_REASONS.has(reason)) store.counter("openclaw_diff_cache_misses_total", "Local diff cache misses by bounded reason; pending reads join an existing load.", {
+					method: evt.name,
+					reason
+				});
+				for (const stage of [
+					"admission",
+					"checkout-resolve",
+					"cache-validate",
+					"worker-queue",
+					"git-wall",
+					"encode"
+				]) {
+					const elapsed = evt.details?.[stage];
+					store.histogram("openclaw_diff_stage_seconds", "Elapsed local diff stages; cache validation includes its worker queue and Git wall time.", {
+						method: evt.name,
+						stage,
+						outcome
+					}, typeof elapsed === "number" ? seconds(elapsed) : void 0, RPC_DURATION_BUCKETS_SECONDS);
+				}
+				return;
+			}
 			if (evt.name === "worktree.preparation") {
-				recordWorktreePreparation(store, evt);
+				const { kind, template, outcome } = evt.details ?? {};
+				if (kind !== "managed" && kind !== "sandbox" || ![
+					"warm",
+					"cold",
+					"unavailable",
+					"reused"
+				].includes(String(template)) || outcome !== "returned" && outcome !== "threw") return;
+				for (const preparationPhase of [
+					"total",
+					"allocate",
+					"checkout",
+					"setup",
+					"templatePrepare",
+					"templateApply",
+					"snapshot",
+					"synchronizeCanonical",
+					"synchronizeProjection",
+					"containerStart",
+					"workspaceLayout"
+				]) {
+					const elapsed = preparationPhase === "total" ? evt.durationMs : evt.details?.[preparationPhase];
+					store.histogram("openclaw_worktree_preparation_seconds", "Elapsed managed worktree preparation time; nested phases are inclusive.", {
+						kind,
+						template: String(template),
+						outcome,
+						phase: preparationPhase
+					}, typeof elapsed === "number" ? seconds(elapsed) : void 0);
+				}
 				return;
 			}
 			const sendPhase = CHAT_SEND_PHASE.exec(evt.name)?.[1];
@@ -403,6 +1000,14 @@ function recordOperationTimingEvent(store, evt, metadata) {
 				}, seconds(evt.durationMs));
 				return;
 			}
+			const startupPhase = CHAT_STARTUP_PHASE.exec(evt.name)?.[1];
+			if (startupPhase) {
+				store.histogram("openclaw_gateway_rpc_stage_seconds", "Elapsed time for completed Gateway RPC owner stages.", {
+					method: "chat.startup",
+					phase: startupPhase
+				}, seconds(evt.durationMs));
+				return;
+			}
 			if (!evt.name.startsWith(CATALOG_LIST_PHASE_PREFIX)) return;
 			const phase = evt.name.slice(CATALOG_LIST_PHASE_PREFIX.length);
 			const duration = seconds(evt.durationMs);
@@ -420,6 +1025,10 @@ function recordOperationTimingEvent(store, evt, metadata) {
 			const labels = { method: evt.method };
 			if (evt.phase === "received") {
 				store.counter("openclaw_gateway_rpc_requests_total", "Authenticated Gateway WebSocket requests received.", labels);
+				store.counter("openclaw_gateway_rpc_client_requests_total", "Gateway RPC requests by bounded handshake client kind.", {
+					method: evt.method,
+					client_kind: evt.clientKind ?? "other"
+				});
 				if (evt.method === "models.list" && evt.modelsList) {
 					const catalog = evt.modelsList;
 					store.counter("openclaw_models_list_requests_total", "Model catalog requests by client kind and bounded request shape.", {
@@ -431,10 +1040,54 @@ function recordOperationTimingEvent(store, evt, metadata) {
 						prepared_only: String(catalog.preparedOnly)
 					});
 				}
+				if (evt.method === "sessions.list" && evt.sessionsList) {
+					const sessions = evt.sessionsList;
+					store.counter("openclaw_sessions_list_requests_total", "Session list requests by client kind and bounded request shape.", {
+						client_kind: sessions.clientKind,
+						source: sessions.source,
+						caller_source: sessions.callerSource,
+						row_mode: sessions.rowMode,
+						filter: sessions.filter
+					});
+				}
+				if (evt.method === "cron.list" && evt.cronList) {
+					const cron = evt.cronList;
+					store.counter("openclaw_cron_list_requests_total", "Cron list requests by client kind and bounded request shape.", {
+						client_kind: cron.clientKind,
+						source: cron.source,
+						scope: cron.scope,
+						compact: String(cron.compact),
+						page: cron.page
+					});
+				}
 				return;
 			}
 			if (evt.phase === "response" && (evt.outcome === "ok" || evt.outcome === "error")) {
+				if (evt.outcome === "ok" && evt.firstResponse !== false && evt.sessionsList?.baseMissReason) store.counter("openclaw_sessions_list_base_misses_total", "Successful full sidebar responses with a supplied base, by miss reason.", { reason: evt.sessionsList.baseMissReason });
 				store.histogram("openclaw_gateway_rpc_response_bytes", "Encoded Gateway RPC response frame size in bytes, including later frames.", labels, evt.responseBytes, RESPONSE_BYTE_BUCKETS);
+				if (evt.responseBytes !== void 0 && evt.sessionsList) {
+					const sessions = evt.sessionsList;
+					store.counter("openclaw_sessions_list_response_bytes_total", "Encoded successful session list response bytes by request shape and row outcome.", {
+						client_kind: sessions.clientKind,
+						source: sessions.source,
+						caller_source: sessions.callerSource,
+						row_mode: sessions.rowMode,
+						filter: sessions.filter,
+						rows_outcome: sessions.rowsOutcome
+					}, evt.responseBytes);
+				}
+				if (evt.chatHistory) {
+					const history = evt.chatHistory;
+					const historyLabels = {
+						client_kind: history.clientKind,
+						source: history.source,
+						shape: history.shape,
+						limit_bucket: history.limitBucket,
+						outcome: history.outcome
+					};
+					if (evt.firstResponse !== false) store.counter("openclaw_chat_history_requests_total", "Successful chat history requests by request shape and response outcome.", historyLabels);
+					if (evt.responseBytes !== void 0) store.counter("openclaw_chat_history_response_bytes_total", "Encoded successful chat history response bytes by request shape and response outcome.", historyLabels, evt.responseBytes);
+				}
 				if (evt.firstResponse === false) return;
 			}
 			store.counter("openclaw_gateway_rpc_outcomes_total", "Gateway RPC observations by phase and outcome.", {
@@ -451,53 +1104,24 @@ function recordOperationTimingEvent(store, evt, metadata) {
 		}
 	}
 }
-function recordWorktreePreparation(store, evt) {
-	const { kind, template, outcome } = evt.details ?? {};
-	if (kind !== "managed" && kind !== "sandbox" || ![
-		"warm",
-		"cold",
-		"unavailable",
-		"reused"
-	].includes(String(template)) || outcome !== "returned" && outcome !== "threw") return;
-	for (const phase of [
-		"total",
-		"allocate",
-		"checkout",
-		"setup",
-		"templatePrepare",
-		"templateApply",
-		"snapshot",
-		"synchronizeCanonical",
-		"synchronizeProjection",
-		"containerStart",
-		"workspaceLayout"
-	]) {
-		const elapsed = phase === "total" ? evt.durationMs : evt.details?.[phase];
-		store.histogram("openclaw_worktree_preparation_seconds", "Elapsed managed worktree preparation time; nested phases are inclusive.", {
-			kind,
-			template: String(template),
-			outcome,
-			phase
-		}, typeof elapsed === "number" ? seconds(elapsed) : void 0);
+//#endregion
+//#region extensions/diagnostics-prometheus/src/service-retention.ts
+function recordSessionRetention(store, evt) {
+	if (evt.type === "sessions.event.rows.reset") {
+		store.counter("openclaw_session_event_rows_reset_total", "Retained session-event wire baselines retired by cause.", { cause: evt.cause }, evt.count);
+		return;
 	}
+	if (evt.type === "sessions.list.retention") {
+		store.gauge("openclaw_sessions_list_retained_views", "Retained session-list views across all publications.", {}, evt.views);
+		store.gauge("openclaw_sessions_list_retained_refs", "Row references and selection entries retained by session-list views.", {}, evt.refs);
+		store.gauge("openclaw_sessions_list_retained_bytes", "Estimated memory retained by session-list views.", {}, evt.estimatedBytes);
+		return;
+	}
+	store.gauge("openclaw_session_event_rows_retained_entries", "Session-event field-hash vectors retained across all connections.", {}, evt.entries);
+	store.gauge("openclaw_session_event_rows_retained_bytes", "Estimated memory retained by session-event field-hash vectors.", {}, evt.estimatedBytes);
 }
 //#endregion
 //#region extensions/diagnostics-prometheus/src/service-sessions.ts
-function createGatewayWorkMetricsRecorder(store) {
-	return (snapshot) => {
-		if (!snapshot) {
-			store.clearGauges("openclaw_sessions_active");
-			store.clearGauges("openclaw_gateway_active_work");
-			return;
-		}
-		for (const state of ["running", "queued"]) store.gauge("openclaw_sessions_active", "Current active sessions in the Gateway session roster by run state.", { state }, snapshot.sessions[state]);
-		for (const kind of [
-			"agentRuns",
-			"chatRuns",
-			"queuedTurns"
-		]) store.gauge("openclaw_gateway_active_work", "Current Gateway work by owner; categories may overlap.", { kind }, snapshot.work[kind]);
-	};
-}
 function recordSessionDiagnosticEvent(store, evt) {
 	switch (evt.type) {
 		case "session.recovery.requested":
@@ -537,60 +1161,62 @@ function recordSessionDiagnosticEvent(store, evt) {
 }
 //#endregion
 //#region extensions/diagnostics-prometheus/src/service-worker.ts
-function recordWorkerRequest(store, event) {
-	store.gauge("openclaw_worker_queue_depth", "Requests awaiting dispatch across worker owners of this kind.", { kind: event.kind }, event.queueDepth);
-	const labels = {
-		kind: event.kind,
-		request_class: event.requestClass
+function createWorkerRequestMetricsRecorder(store) {
+	return (kind, requestClass, requestPhase, queueDepth, queueWaitMs, durationMs, timing) => {
+		store.gauge("openclaw_worker_queue_depth", "Requests awaiting dispatch across worker owners of this kind.", { kind }, queueDepth);
+		const labels = {
+			kind,
+			request_class: requestClass
+		};
+		store.histogram("openclaw_worker_queue_wait_seconds", "Elapsed time from worker request enqueue to dispatch.", labels, seconds(queueWaitMs));
+		store.histogram("openclaw_worker_request_seconds", "Elapsed time from worker dispatch to reply or failure, including preparation and transport.", labels, seconds(durationMs));
+		if (requestPhase !== "completed" || !timing) return;
+		for (const [phase, start, end] of [
+			[
+				"dispatch",
+				"dispatched",
+				"posted"
+			],
+			[
+				"delivery",
+				"posted",
+				"received"
+			],
+			[
+				"input",
+				"received",
+				"inputReady"
+			],
+			[
+				"prepare",
+				"inputReady",
+				"executeStarted"
+			],
+			[
+				"execute",
+				"executeStarted",
+				"executeFinished"
+			],
+			[
+				"result",
+				"executeFinished",
+				"replied"
+			],
+			[
+				"reply",
+				"replied",
+				"replyReceived"
+			]
+		]) {
+			const started = timing[start];
+			const finished = timing[end];
+			if (started === void 0 || finished === void 0) continue;
+			store.histogram("openclaw_worker_request_phase_seconds", "Elapsed time within an observed SQLite worker request phase, including transport.", {
+				...labels,
+				phase
+			}, seconds(finished - started));
+		}
 	};
-	store.histogram("openclaw_worker_queue_wait_seconds", "Elapsed time from worker request enqueue to dispatch.", labels, seconds(event.queueWaitMs));
-	store.histogram("openclaw_worker_request_seconds", "Elapsed time from worker dispatch to reply or failure, including preparation and transport.", labels, seconds(event.durationMs));
-	if (event.phase !== "completed" || !event.timing) return;
-	for (const [phase, start, end] of [
-		[
-			"dispatch",
-			"dispatched",
-			"posted"
-		],
-		[
-			"delivery",
-			"posted",
-			"received"
-		],
-		[
-			"input",
-			"received",
-			"inputReady"
-		],
-		[
-			"prepare",
-			"inputReady",
-			"executeStarted"
-		],
-		[
-			"execute",
-			"executeStarted",
-			"executeFinished"
-		],
-		[
-			"result",
-			"executeFinished",
-			"replied"
-		],
-		[
-			"reply",
-			"replied",
-			"replyReceived"
-		]
-	]) {
-		const started = event.timing[start];
-		const finished = event.timing[end];
-		if (started === void 0 || finished === void 0) continue;
-		store.histogram("openclaw_worker_request_phase_seconds", "Elapsed time within an observed SQLite worker request phase, including transport.", {
-			...labels,
-			phase
-		}, seconds(finished - started));
-	}
 }
 //#endregion
 //#region extensions/diagnostics-prometheus/src/service.ts
@@ -626,36 +1252,6 @@ function safeErrorMessage(err) {
 	const message = err instanceof Error ? err.message ?? err.name : String(err);
 	return truncateUtf16Safe(redactSensitiveText(message).replaceAll("\0", " ").replace(/[\r\n\t\u2028\u2029]/gu, " "), 500);
 }
-function renderPrometheusMetrics(store) {
-	const snapshot = store.snapshot();
-	const lines = [];
-	const emitted = /* @__PURE__ */ new Set();
-	const emitHeader = (name, type, help) => {
-		if (emitted.has(name)) return;
-		emitted.add(name);
-		lines.push(`# HELP ${name} ${escapeHelp(help)}`);
-		lines.push(`# TYPE ${name} ${type}`);
-	};
-	for (const [type, entries] of [["counter", snapshot.counters], ["gauge", snapshot.gauges]]) {
-		entries.sort(([left], [right]) => left.localeCompare(right));
-		for (const [key, sample] of entries) {
-			const name = key.split("|", 1)[0] ?? "";
-			emitHeader(name, type, sample.help);
-			lines.push(`${name}${formatLabels(sample.labels)} ${formatPrometheusNumber(sample.value)}`);
-		}
-	}
-	snapshot.histograms.sort(([left], [right]) => left.localeCompare(right));
-	for (const [key, sample] of snapshot.histograms) {
-		const name = key.split("|", 1)[0] ?? "";
-		emitHeader(name, "histogram", sample.help);
-		for (let index = 0; index < sample.buckets.length; index += 1) lines.push(`${sample.bucketPrefixes[index]}${formatPrometheusNumber(sample.counts[index] ?? 0)}`);
-		lines.push(`${sample.bucketPrefixes[sample.buckets.length]}${formatPrometheusNumber(sample.count)}`);
-		lines.push(`${name}_sum${sample.labels} ${formatPrometheusNumber(sample.sum)}`);
-		lines.push(`${name}_count${sample.labels} ${formatPrometheusNumber(sample.count)}`);
-	}
-	lines.push("");
-	return lines.join("\n");
-}
 function webhookLabels(evt) {
 	return {
 		channel: normalizeDiagnosticValue(evt.channel),
@@ -665,16 +1261,23 @@ function webhookLabels(evt) {
 function recordDiagnosticEvent(store, evt, metadata) {
 	if (!metadata.trusted && !isInternalDiagnosticEventMetadata(metadata)) return;
 	switch (evt.type) {
-		case "worker.request":
-			if (metadata.trusted) recordWorkerRequest(store, evt);
+		case "gateway.ws.connections":
+			if (metadata.trusted) recordGatewayWsConnections(store, evt.operators);
+			return;
+		case "sessions.list.retention":
+		case "sessions.event.retention":
+		case "sessions.event.rows.reset":
+			if (metadata.trusted) recordSessionRetention(store, evt);
 			return;
 		case "diagnostic.phase.completed":
 		case "secret.egress":
 		case "tool.catalog":
 		case "gateway.rpc":
+		case "sessions.list.baseline.retired":
 		case "gateway.http.cancelled":
 		case "diagnostic.gc":
 		case "gateway.event_loop.sample":
+		case "gateway.main_thread.stall":
 			recordOperationTimingEvent(store, evt, metadata);
 			return;
 		case "model.usage":
@@ -850,17 +1453,22 @@ function recordDiagnosticEvent(store, evt, metadata) {
 			recordSessionDiagnosticEvent(store, evt);
 			return;
 		case "queue.lane.enqueue":
-		case "queue.lane.dequeue":
-			store.gauge("openclaw_queue_lane_size", "Current diagnostic queue lane size.", { lane: normalizeDiagnosticLane(evt.lane) }, asNonNegativeFiniteNumber(evt.queueSize));
-			if (evt.type === "queue.lane.dequeue") store.histogram("openclaw_queue_lane_wait_seconds", "Queue lane wait time in seconds.", { lane: normalizeDiagnosticLane(evt.lane) }, seconds(evt.waitMs));
+		case "queue.lane.dequeue": {
+			const labels = { lane: normalizeDiagnosticLane(evt.lane) };
+			store.gauge("openclaw_queue_lane_size", "Current diagnostic queue lane size.", labels, asNonNegativeFiniteNumber(evt.queueSize));
+			if (evt.type === "queue.lane.dequeue") store.histogram("openclaw_queue_lane_wait_seconds", "Queue lane wait time in seconds.", labels, seconds(evt.waitMs));
 			return;
+		}
 		case "session.state":
 		case "session.stuck":
 		case "session.turn.created":
 			recordSessionDiagnosticEvent(store, evt);
 			return;
 		case "diagnostic.child_process.spawn":
-			recordChildProcessSpawn(store, evt);
+			store.counter("openclaw_child_process_spawn_total", "Successful child launches through the shared spawn and exec owners.", {
+				family: normalizeDiagnosticValue(evt.family),
+				operation: normalizeDiagnosticValue(evt.operation ?? (evt.family === "git" ? "unknown" : "none"))
+			}, asNonNegativeFiniteNumber(evt.count) ?? 0);
 			return;
 		case "diagnostic.memory.sample":
 			recordMemorySample(store, evt.memory, BYTE_BUCKETS);
@@ -945,23 +1553,24 @@ function createMetricsHandler(store) {
 			res.end("Method Not Allowed");
 			return true;
 		}
-		const body = renderPrometheusMetrics(store);
+		const body = store.render();
 		res.statusCode = 200;
 		res.setHeader("Cache-Control", "no-store");
 		res.setHeader("Content-Type", "text/plain; version=0.0.4; charset=utf-8");
-		res.setHeader("Content-Length", String(Buffer.byteLength(body)));
-		if (req.method === "HEAD") {
-			res.end();
-			return true;
-		}
-		res.end(body);
+		res.setHeader("Content-Length", String(body.length));
+		res.flushHeaders();
+		res.end(req.method === "HEAD" ? void 0 : body, (error) => {
+			if (!error) body.buffer.transfer(0);
+		});
 		return true;
 	};
 }
 function createDiagnosticsPrometheusExporter() {
-	const store = createPrometheusMetricStore();
-	let unsubscribe;
-	let unsubscribeWork;
+	let logger;
+	const store = createPrometheusMetricStore((family) => {
+		logger?.warn(`diagnostics-prometheus: series budget reached for ${family}; new label sets are being dropped. See openclaw_prometheus_family_series_dropped_total.`);
+	});
+	let subscriptions = [];
 	let internalDiagnostics;
 	const reportExporterStatus = (update) => {
 		try {
@@ -976,7 +1585,6 @@ function createDiagnosticsPrometheusExporter() {
 	};
 	return {
 		handler: createMetricsHandler(store),
-		render: () => renderPrometheusMetrics(store),
 		service: {
 			id: "diagnostics-prometheus",
 			start(ctx) {
@@ -985,19 +1593,44 @@ function createDiagnosticsPrometheusExporter() {
 					ctx.logger.error("diagnostics-prometheus: internal diagnostics capability unavailable");
 					return;
 				}
+				logger = ctx.logger;
+				reserveMainGcHistograms(store);
 				const identity = isDiagnosticsEnabled(ctx.config) ? ctx.internalDiagnostics?.getRuntimeIdentity?.() : void 0;
 				if (identity) store.gauge("openclaw_gateway_build_info", "Identity of the hosting process and its loaded build; not a health or exporter epoch.", {
 					process_instance_id: identity.processInstanceId,
 					...identity.buildId ? { build_id: identity.buildId } : {}
 				}, 1);
-				unsubscribeWork = ctx.internalDiagnostics?.onGatewayWorkMetrics?.(createGatewayWorkMetricsRecorder(store));
-				unsubscribe = subscribe((event, metadata) => {
-					try {
-						recordDiagnosticEvent(store, event, metadata);
-					} catch (err) {
-						ctx.logger.error(`diagnostics-prometheus: event handler failed (${event.type}): ${safeErrorMessage(err)}`);
-					}
-				}, { exclude: ["log.record"] }, { includePrivateData: false });
+				subscriptions = [
+					ctx.internalDiagnostics?.onGatewayWorkMetrics?.((snapshot) => {
+						if (!snapshot) {
+							store.clearGauges("openclaw_sessions_active");
+							store.clearGauges("openclaw_gateway_active_work");
+							return;
+						}
+						for (const state of ["running", "queued"]) store.gauge("openclaw_sessions_active", "Current active sessions in the Gateway session roster by run state.", { state }, snapshot.sessions[state]);
+						for (const kind of [
+							"agentRuns",
+							"chatRuns",
+							"queuedTurns"
+						]) store.gauge("openclaw_gateway_active_work", "Current Gateway work by owner; categories may overlap.", { kind }, snapshot.work[kind]);
+					}),
+					ctx.internalDiagnostics?.onGatewayWsMetrics?.(createGatewayWsMetricsRecorder(store)),
+					ctx.internalDiagnostics?.onWorkerRequestMetrics?.(createWorkerRequestMetricsRecorder(store)),
+					subscribe((event, metadata) => {
+						try {
+							recordDiagnosticEvent(store, event, metadata);
+						} catch (err) {
+							ctx.logger.error(`diagnostics-prometheus: event handler failed (${event.type}): ${safeErrorMessage(err)}`);
+						}
+					}, {
+						exclude: [
+							"log.record",
+							"worker.request",
+							"gateway.ws.event"
+						],
+						includePromptStats: false
+					}, { includePrivateData: false })
+				];
 				internalDiagnostics = ctx.internalDiagnostics;
 				reportExporterStatus({
 					signal: "metrics",
@@ -1007,10 +1640,8 @@ function createDiagnosticsPrometheusExporter() {
 				});
 			},
 			stop() {
-				unsubscribeWork?.();
-				unsubscribeWork = void 0;
-				unsubscribe?.();
-				unsubscribe = void 0;
+				for (const unsubscribe of subscriptions) unsubscribe?.();
+				subscriptions = [];
 				reportExporterStatus({
 					signal: "metrics",
 					transport: "prometheus-scrape",
@@ -1018,6 +1649,7 @@ function createDiagnosticsPrometheusExporter() {
 				});
 				internalDiagnostics = void 0;
 				store.reset();
+				logger = void 0;
 			}
 		}
 	};