@camstack/core 0.1.15 → 0.1.17

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

@@ -1,7 +1,916 @@
-import {
-  NativeMetricsAddon
-} from "../../chunk-4XHB7IHT.mjs";
-export {
-  NativeMetricsAddon as default
+import * as fs from "node:fs";
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+import { BaseAddon, EventCategory, createEvent, metricsProviderCapability } from "@camstack/types";
+import * as os from "node:os";
+//#region src/builtins/native-metrics/native-metrics-provider.ts
+var IS_DARWIN = os.platform() === "darwin";
+var IS_LINUX = os.platform() === "linux";
+var NativeMetricsProvider = class {
+	id = "native";
+	cachedSnapshot = null;
+	samplingTimer = null;
+	macMemTimer = null;
+	prevCpu;
+	diagnostics = null;
+	consecutiveSampleErrors = 0;
+	constructor() {
+		this.prevCpu = aggregateCpuTimes();
+	}
+	/**
+	* Optional diagnostics sink for sampling errors. The first failure and
+	* every Nth failure thereafter are reported so a permanently-broken
+	* collector doesn't spam logs but is still observable.
+	*/
+	setDiagnostics(diag) {
+		this.diagnostics = diag;
+	}
+	startSampling(intervalMs) {
+		if (IS_DARWIN) {
+			sampleMacMemory(this);
+			this.macMemTimer = setInterval(() => sampleMacMemory(this), 5e3);
+			if (this.macMemTimer.unref) this.macMemTimer.unref();
+		}
+		this.collectSnapshot().then((s) => {
+			this.cachedSnapshot = s;
+			this.consecutiveSampleErrors = 0;
+		}).catch((err) => this.reportSampleError(err));
+		this.samplingTimer = setInterval(() => {
+			this.collectSnapshot().then((s) => {
+				this.cachedSnapshot = s;
+				this.consecutiveSampleErrors = 0;
+			}).catch((err) => this.reportSampleError(err));
+		}, intervalMs);
+		if (this.samplingTimer.unref) this.samplingTimer.unref();
+	}
+	reportSampleError(err) {
+		this.consecutiveSampleErrors++;
+		if (!this.diagnostics) return;
+		if (!(this.consecutiveSampleErrors === 1 || this.consecutiveSampleErrors % 60 === 0)) return;
+		this.diagnostics.warn("metrics-provider sample failed", {
+			consecutiveErrors: this.consecutiveSampleErrors,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+	stopSampling() {
+		if (this.samplingTimer) {
+			clearInterval(this.samplingTimer);
+			this.samplingTimer = null;
+		}
+		if (this.macMemTimer) {
+			clearInterval(this.macMemTimer);
+			this.macMemTimer = null;
+		}
+	}
+	async collectSnapshot() {
+		const cpu = this.sampleCpu();
+		const memory = this.getMemoryInfo();
+		const processInfo = getProcessResources();
+		const [gpu, network, disk, cpuTemp] = await Promise.all([
+			getGpuInfoInternal().catch(() => null),
+			takeNetworkIoSnapshot(),
+			takeDiskIoSnapshot(),
+			getCpuTemperatureInternal().catch(() => null)
+		]);
+		const snapshot = {
+			cpu,
+			memory,
+			gpu,
+			network,
+			disk,
+			pressure: {
+				cpu: getPressure("cpu"),
+				memory: getPressure("memory"),
+				io: getPressure("io")
+			},
+			process: processInfo,
+			cpuTemperature: cpuTemp,
+			timestampMs: Date.now()
+		};
+		this.cachedSnapshot = snapshot;
+		return snapshot;
+	}
+	async getCached() {
+		return this.cachedSnapshot;
+	}
+	async getCurrent() {
+		const s = this.cachedSnapshot ?? await this.collectSnapshot();
+		const mb = (bytes) => Math.round(bytes / 1024 / 1024);
+		return {
+			cpuPercent: s.cpu.total,
+			memoryPercent: s.memory.percent,
+			memoryUsedMB: mb(s.memory.usedBytes),
+			memoryTotalMB: mb(s.memory.totalBytes),
+			temperature: s.cpuTemperature ?? void 0,
+			gpuPercent: s.gpu?.utilization,
+			gpuMemoryPercent: s.gpu && s.gpu.memoryTotalBytes > 0 ? Math.round(s.gpu.memoryUsedBytes / s.gpu.memoryTotalBytes * 1e3) / 10 : void 0
+		};
+	}
+	async getDiskSpace(input) {
+		return getDiskSpaceInternal(input.dirPath);
+	}
+	async getGpuInfo() {
+		return getGpuInfoInternal();
+	}
+	async getCpuTemperature() {
+		return getCpuTemperatureInternal();
+	}
+	async getProcessStats(input) {
+		const { getPidStats } = await import("../../resource-monitor-DcQdKGYU.mjs").then((n) => n.r);
+		const raw = await getPidStats(input.pids);
+		const result = [];
+		for (const [pid, s] of raw) result.push({
+			pid,
+			cpu: s.cpu,
+			memory: s.memory
+		});
+		return result;
+	}
+	sampleCpu() {
+		const curr = aggregateCpuTimes();
+		const prev = this.prevCpu;
+		this.prevCpu = curr;
+		const dUser = curr.user - prev.user;
+		const dNice = curr.nice - prev.nice;
+		const dSys = curr.sys - prev.sys;
+		const dIrq = curr.irq - prev.irq;
+		const dIdle = curr.idle - prev.idle;
+		const dTotal = dUser + dNice + dSys + dIrq + dIdle;
+		const pct = (v) => dTotal === 0 ? 0 : Math.round(v / dTotal * 1e3) / 10;
+		return {
+			total: pct(dUser + dNice + dSys + dIrq),
+			user: pct(dUser),
+			system: pct(dSys),
+			irq: pct(dIrq),
+			nice: pct(dNice),
+			loadAvg: os.loadavg(),
+			cores: os.cpus().length
+		};
+	}
+	/** Cached macOS memory (set by sampleMacMemory timer). */
+	_cachedMacMem = null;
+	getMemoryInfo() {
+		const total = os.totalmem();
+		if (total === 0) return {
+			percent: 0,
+			totalBytes: 0,
+			usedBytes: 0,
+			availableBytes: 0,
+			swapUsedBytes: 0,
+			swapTotalBytes: 0
+		};
+		if (IS_DARWIN && this._cachedMacMem !== null) return this._cachedMacMem;
+		const free = os.freemem();
+		const used = total - free;
+		let swapUsedBytes = 0;
+		let swapTotalBytes = 0;
+		if (IS_LINUX) try {
+			const meminfo = fs.readFileSync("/proc/meminfo", "utf-8");
+			const swapTotal = parseInt(meminfo.match(/SwapTotal:\s+(\d+)/)?.[1] ?? "0", 10) * 1024;
+			const swapFree = parseInt(meminfo.match(/SwapFree:\s+(\d+)/)?.[1] ?? "0", 10) * 1024;
+			swapTotalBytes = swapTotal;
+			swapUsedBytes = swapTotal - swapFree;
+		} catch {}
+		return {
+			percent: Math.round((total - free) / total * 1e3) / 10,
+			totalBytes: total,
+			usedBytes: used,
+			availableBytes: free,
+			swapUsedBytes,
+			swapTotalBytes
+		};
+	}
 };
+function aggregateCpuTimes() {
+	const cpus = os.cpus();
+	let user = 0, nice = 0, sys = 0, irq = 0, idle = 0;
+	for (const cpu of cpus) {
+		user += cpu.times.user;
+		nice += cpu.times.nice;
+		sys += cpu.times.sys;
+		irq += cpu.times.irq;
+		idle += cpu.times.idle;
+	}
+	return {
+		user,
+		nice,
+		sys,
+		irq,
+		idle
+	};
+}
+function sampleMacMemory(provider) {
+	try {
+		const output = execFileSync("vm_stat", {
+			timeout: 2e3,
+			encoding: "utf-8"
+		});
+		const pageSize = 16384;
+		const parse = (label) => {
+			const match = output.match(new RegExp(`${label}:\\s+(\\d+)`));
+			return match ? parseInt(match[1], 10) * pageSize : 0;
+		};
+		const free = parse("Pages free");
+		const inactive = parse("Pages inactive");
+		const purgeable = parse("Pages purgeable");
+		const speculative = parse("Pages speculative");
+		const available = free + inactive + purgeable + speculative;
+		const total = os.totalmem();
+		const used = total - available;
+		let swapUsedBytes = 0;
+		let swapTotalBytes = 0;
+		try {
+			const swapOut = execFileSync("sysctl", ["-n", "vm.swapusage"], {
+				timeout: 2e3,
+				encoding: "utf-8"
+			});
+			const totalMatch = swapOut.match(/total\s*=\s*([\d.]+)M/);
+			const usedMatch = swapOut.match(/used\s*=\s*([\d.]+)M/);
+			if (totalMatch) swapTotalBytes = parseFloat(totalMatch[1]) * 1024 * 1024;
+			if (usedMatch) swapUsedBytes = parseFloat(usedMatch[1]) * 1024 * 1024;
+		} catch {}
+		provider._cachedMacMem = {
+			percent: Math.round(used / total * 1e3) / 10,
+			totalBytes: total,
+			usedBytes: used,
+			availableBytes: available,
+			swapUsedBytes,
+			swapTotalBytes
+		};
+	} catch {
+		provider._cachedMacMem = null;
+	}
+}
+function getDiskSpaceInternal(dirPath) {
+	return new Promise((resolve, reject) => {
+		fs.statfs(dirPath, (err, stats) => {
+			if (err) return reject(err);
+			const totalBytes = stats.blocks * stats.bsize;
+			const availableBytes = stats.bavail * stats.bsize;
+			const usedBytes = totalBytes - stats.bfree * stats.bsize;
+			resolve({
+				path: dirPath,
+				totalBytes,
+				usedBytes,
+				availableBytes,
+				percent: totalBytes > 0 ? Math.round(usedBytes / totalBytes * 1e3) / 10 : 0
+			});
+		});
+	});
+}
+async function takeDiskIoSnapshot() {
+	const now = Date.now();
+	if (IS_LINUX) try {
+		const data = fs.readFileSync("/proc/diskstats", "utf-8");
+		let readOps = 0, readBytes = 0, writeOps = 0, writeBytes = 0;
+		for (const line of data.split("\n")) {
+			const parts = line.trim().split(/\s+/);
+			if (parts.length < 14) continue;
+			const devName = parts[2];
+			if (/\d+$/.test(devName) && !/^nvme\d+n\d+$/.test(devName)) continue;
+			readOps += parseInt(parts[3], 10) || 0;
+			readBytes += (parseInt(parts[5], 10) || 0) * 512;
+			writeOps += parseInt(parts[7], 10) || 0;
+			writeBytes += (parseInt(parts[9], 10) || 0) * 512;
+		}
+		return {
+			readBytes,
+			writeBytes,
+			readOps,
+			writeOps,
+			timestampMs: now
+		};
+	} catch {}
+	return {
+		readBytes: 0,
+		writeBytes: 0,
+		readOps: 0,
+		writeOps: 0,
+		timestampMs: now
+	};
+}
+async function takeNetworkIoSnapshot() {
+	const now = Date.now();
+	if (IS_LINUX) try {
+		const data = fs.readFileSync("/proc/net/dev", "utf-8");
+		let rxBytes = 0, txBytes = 0, rxPackets = 0, txPackets = 0, rxErrors = 0, txErrors = 0;
+		for (const line of data.split("\n")) {
+			const match = line.match(/^\s*(\w+):\s+(.+)$/);
+			if (!match) continue;
+			if (match[1] === "lo") continue;
+			const cols = match[2].trim().split(/\s+/);
+			rxBytes += parseInt(cols[0], 10) || 0;
+			rxPackets += parseInt(cols[1], 10) || 0;
+			rxErrors += parseInt(cols[2], 10) || 0;
+			txBytes += parseInt(cols[8], 10) || 0;
+			txPackets += parseInt(cols[9], 10) || 0;
+			txErrors += parseInt(cols[10], 10) || 0;
+		}
+		return {
+			rxBytes,
+			txBytes,
+			rxPackets,
+			txPackets,
+			rxErrors,
+			txErrors,
+			timestampMs: now
+		};
+	} catch {}
+	if (IS_DARWIN) try {
+		const stdout = await execAsync("netstat", ["-ib"]);
+		let rxBytes = 0, txBytes = 0, rxPackets = 0, txPackets = 0, rxErrors = 0, txErrors = 0;
+		for (const line of stdout.split("\n")) {
+			const parts = line.trim().split(/\s+/);
+			if (parts.length < 11) continue;
+			if (parts[0] === "lo0" || parts[0] === "Name") continue;
+			if (!parts[2]?.startsWith("Link#")) continue;
+			rxPackets += parseInt(parts[4], 10) || 0;
+			rxErrors += parseInt(parts[5], 10) || 0;
+			rxBytes += parseInt(parts[6], 10) || 0;
+			txPackets += parseInt(parts[7], 10) || 0;
+			txErrors += parseInt(parts[8], 10) || 0;
+			txBytes += parseInt(parts[9], 10) || 0;
+		}
+		return {
+			rxBytes,
+			txBytes,
+			rxPackets,
+			txPackets,
+			rxErrors,
+			txErrors,
+			timestampMs: now
+		};
+	} catch {}
+	return {
+		rxBytes: 0,
+		txBytes: 0,
+		rxPackets: 0,
+		txPackets: 0,
+		rxErrors: 0,
+		txErrors: 0,
+		timestampMs: now
+	};
+}
+async function getCpuTemperatureInternal() {
+	if (IS_LINUX) for (const p of ["/sys/class/thermal/thermal_zone0/temp", "/sys/class/hwmon/hwmon0/temp1_input"]) try {
+		const raw = fs.readFileSync(p, "utf-8").trim();
+		const millideg = parseInt(raw, 10);
+		if (!isNaN(millideg)) return Math.round(millideg / 100) / 10;
+	} catch {
+		continue;
+	}
+	if (IS_DARWIN) try {
+		const match = (await execAsync("sudo", [
+			"-n",
+			"powermetrics",
+			"--samplers",
+			"smc",
+			"-i",
+			"1",
+			"-n",
+			"1"
+		], 3e3)).match(/CPU die temperature:\s+([\d.]+)\s*C/);
+		if (match) return Math.round(parseFloat(match[1]) * 10) / 10;
+	} catch {}
+	return null;
+}
+async function getGpuInfoInternal() {
+	if (IS_DARWIN) try {
+		const utilMatch = (await execAsync("ioreg", [
+			"-r",
+			"-d",
+			"1",
+			"-c",
+			"IOAccelerator"
+		])).match(/"GPU Core Utilization"\s*=\s*(\d+)/);
+		const util = utilMatch ? parseInt(utilMatch[1], 10) : 0;
+		const utilPct = util > 1e3 ? Math.round(util / 1e7) : util;
+		return {
+			utilization: Math.min(100, utilPct),
+			model: "Apple Silicon GPU",
+			memoryUsedBytes: 0,
+			memoryTotalBytes: 0,
+			temperature: null
+		};
+	} catch {}
+	if (IS_LINUX) try {
+		const parts = (await execAsync("nvidia-smi", ["--query-gpu=utilization.gpu,name,memory.used,memory.total,temperature.gpu", "--format=csv,noheader,nounits"])).trim().split(",").map((s) => s.trim());
+		if (parts.length >= 5) return {
+			utilization: parseInt(parts[0], 10) || 0,
+			model: parts[1] ?? "Unknown GPU",
+			memoryUsedBytes: (parseInt(parts[2], 10) || 0) * 1024 * 1024,
+			memoryTotalBytes: (parseInt(parts[3], 10) || 0) * 1024 * 1024,
+			temperature: parseInt(parts[4], 10) || null
+		};
+	} catch {}
+	return null;
+}
+function getProcessResources() {
+	let openFds = 0;
+	let threadCount = 0;
+	if (IS_LINUX) {
+		try {
+			openFds = fs.readdirSync(`/proc/${process.pid}/fd`).length;
+		} catch {}
+		try {
+			const match = fs.readFileSync(`/proc/${process.pid}/status`, "utf-8").match(/Threads:\s+(\d+)/);
+			if (match) threadCount = parseInt(match[1], 10);
+		} catch {}
+	}
+	const nodeProcess = process;
+	return {
+		openFds,
+		threadCount,
+		activeHandles: (nodeProcess._getActiveHandles?.() ?? []).length,
+		activeRequests: (nodeProcess._getActiveRequests?.() ?? []).length
+	};
+}
+function getPressure(resource) {
+	if (!IS_LINUX) return null;
+	try {
+		const data = fs.readFileSync(`/proc/pressure/${resource}`, "utf-8");
+		const parseLine = (prefix) => {
+			const match = data.match(new RegExp(`${prefix} avg10=(\\d+\\.\\d+) avg60=(\\d+\\.\\d+) avg300=(\\d+\\.\\d+)`));
+			if (!match) return null;
+			return {
+				avg10: parseFloat(match[1]),
+				avg60: parseFloat(match[2]),
+				avg300: parseFloat(match[3])
+			};
+		};
+		const some = parseLine("some");
+		if (!some) return null;
+		return {
+			some,
+			full: parseLine("full")
+		};
+	} catch {
+		return null;
+	}
+}
+function execAsync(cmd, args, timeoutMs = 5e3) {
+	return new Promise((resolve, reject) => {
+		execFile(cmd, args, { timeout: timeoutMs }, (err, stdout) => {
+			if (err) return reject(err);
+			resolve(stdout);
+		});
+	});
+}
+//#endregion
+//#region src/builtins/native-metrics/native-metrics.addon.ts
+var execFileAsync = promisify(execFile);
+/**
+* Regex matching camstack-related command lines. We surface anything with
+* an obvious camstack fingerprint so operators can spot stray inference
+* pools, leaked tsx watchers, and zombie node workers in the Cluster →
+* Agent → Processes tab.
+*
+* Patterns mirror `scripts/hunt-zombies.sh` — keep them in sync when
+* adding a new long-lived subprocess.
+*/
+var CAMSTACK_CMD_RE = /(camstack|tsx\s+watch\s.*launcher\.ts|packages\/agent\/dist\/cli\.js|inference_pool\.py|bench-(inference-pool|nodeav)|node .*\/packages\/)/;
+/**
+* Boundary patterns: ancestry walks that pass through a process whose
+* command line matches one of these are considered to be inside an
+* "intentional camstack tree". Anything reachable by walking up the
+* pid tree from such a boundary is `system` — not a ghost.
+*
+* The boundaries are:
+*  - `tsx watch .../launcher.ts` — hub launcher (npm run dev:server)
+*  - `node .../packages/agent/dist/cli.js` — agent CLI (dev-cluster, npm run dev:agent)
+*  - `concurrently` — dev-cluster orchestrator that runs hub + admin-ui + agents
+*  - `npm exec ` / `npm-cli.js` — npm wrappers driving the above
+*  - `vite` — admin-ui dev server (sibling of hub under concurrently)
+*
+* The classification logic (`classifyByAncestry`) walks each candidate
+* pid up to ppid=1; if any ancestor matches this regex, the candidate
+* is `system`. Reaching ppid=1 without crossing a boundary = `ghost`.
+*/
+var SUPERVISOR_BOUNDARY_RE = /(tsx\s+watch\s.*launcher\.ts|packages\/agent\/dist\/cli\.js|\.bin\/concurrently|\/concurrently\/dist|\bnpm-cli\.js\b|npm exec |\.bin\/vite|\/vite\/bin\/vite\.js|node_modules\/\.bin\/(vite|concurrently|tsup|rollup|esbuild|tsx)(\s|$))/;
+/**
+* Cadence for the per-node metric snapshot bus events. ~5 s matches
+* the existing UI polling cadence (ProcessesTab, ProcessResources)
+* and stays within the sampling interval so consumers always see a
+* fresh-from-OS payload.
+*/
+var METRICS_SNAPSHOT_INTERVAL_MS = 5e3;
+/**
+* Force a metrics-snapshot emit at least every 60s even when the
+* coarsened payload looks unchanged. Without this an idle node
+* (steady CPU within ±5%, no process churn) goes silent on the
+* bus and the UI's "node alive" chip can stale out.
+*/
+var METRICS_SNAPSHOT_HEARTBEAT_MS = 6e4;
+/**
+* Coarsen CPU/mem percentages to integer buckets before deduping.
+* Without this every 5s tick differs by ±0.3% and the equality check
+* always fails, so the snapshot fans out unconditionally.
+*/
+function coarsenResourcesSnapshot(snapshot) {
+	if (!snapshot || typeof snapshot !== "object") return JSON.stringify(snapshot);
+	const round = (v) => {
+		if (typeof v === "number") {
+			if (v >= 0 && v <= 100) return Math.round(v / 5) * 5;
+			return Math.round(v / 1e5) * 1e5;
+		}
+		if (Array.isArray(v)) return v.map(round);
+		if (v && typeof v === "object") {
+			const out = {};
+			for (const [k, val] of Object.entries(v)) out[k] = round(val);
+			return out;
+		}
+		return v;
+	};
+	return JSON.stringify(round(snapshot));
+}
+/**
+* Coarsen a process list before deduping — pid, addonId, state +
+* bucketed cpu%. Drops cmdline / cwd / start time / uptime which
+* change every tick on a process that's just running. The result
+* is "process X has the same role and roughly the same load" =
+* skip emit.
+*/
+function coarsenProcessList(processes) {
+	const summary = processes.filter((p) => !!p && typeof p === "object").map((p) => {
+		return [
+			p["pid"],
+			p["addonId"],
+			p["state"],
+			typeof p["cpuPercent"] === "number" ? Math.round(p["cpuPercent"] / 5) * 5 : null,
+			typeof p["memoryRss"] === "number" ? Math.round(p["memoryRss"] / (50 * 1024 * 1024)) : null
+		];
+	});
+	return JSON.stringify(summary);
+}
+function narrowWorkerState(state) {
+	switch (state) {
+		case "starting":
+		case "running":
+		case "stopping":
+		case "stopped":
+		case "crashed": return state;
+		default: return "running";
+	}
+}
+/**
+* Native metrics — CPU, memory, disk usage sampling.
+* Settings appear under Cluster → NodeDetail → Settings.
+*/
+var NativeMetricsAddon = class extends BaseAddon {
+	provider = null;
+	startedAtMs = Date.now();
+	snapshotTimer = null;
+	/**
+	* Snapshot-equality cache for the resources + processes emit.
+	* Stores the coarsened JSON and timestamp; a tick where the
+	* coarsened payload matches the cache (and the heartbeat hasn't
+	* elapsed) is skipped.
+	*/
+	lastResourcesEmit = null;
+	lastProcessesEmit = null;
+	constructor() {
+		super({ samplingIntervalMs: 5e3 });
+	}
+	async onInitialize() {
+		const provider = new NativeMetricsProvider();
+		provider.setDiagnostics({ warn: (message, meta) => this.ctx.logger.warn(message, { meta: meta ?? {} }) });
+		provider.startSampling(this.config.samplingIntervalMs);
+		this.provider = provider;
+		this.startedAtMs = Date.now();
+		this.ctx.logger.info("Native metrics provider started", { meta: { intervalMs: this.config.samplingIntervalMs } });
+		const composed = {
+			collectSnapshot: () => provider.collectSnapshot(),
+			getCached: () => provider.getCached(),
+			getCurrent: () => provider.getCurrent(),
+			getDiskSpace: (params) => provider.getDiskSpace(params),
+			getGpuInfo: () => provider.getGpuInfo(),
+			getCpuTemperature: () => provider.getCpuTemperature(),
+			getProcessStats: (params) => provider.getProcessStats(params),
+			listAddonInstances: () => this.listAddonInstances(),
+			getAddonStats: (params) => this.getAddonStats(params.addonId),
+			listNodeProcesses: () => this.listNodeProcesses(),
+			killProcess: (params) => this.killProcess(params)
+		};
+		this.snapshotTimer = setInterval(() => this.emitMetricsSnapshots(), METRICS_SNAPSHOT_INTERVAL_MS);
+		return [{
+			capability: metricsProviderCapability,
+			provider: composed
+		}];
+	}
+	async onShutdown() {
+		if (this.snapshotTimer) {
+			clearInterval(this.snapshotTimer);
+			this.snapshotTimer = null;
+		}
+		this.provider?.stopSampling();
+		this.provider = null;
+	}
+	/**
+	* Emit one `metrics.node-resources-snapshot` + one
+	* `metrics.node-processes-snapshot` for this node. UI consumers
+	* subscribe and read state directly from the payload.
+	*/
+	async emitMetricsSnapshots() {
+		const provider = this.provider;
+		const eventBus = this.ctx.eventBus;
+		if (!provider || !eventBus) return;
+		const rawNodeId = this.ctx.kernel.localNodeId ?? this.ctx.id;
+		const nodeId = rawNodeId.includes("/") ? rawNodeId.split("/")[0] : rawNodeId;
+		const timestamp = Date.now();
+		try {
+			const snapshot = await provider.getCached() ?? await provider.collectSnapshot();
+			const coarse = coarsenResourcesSnapshot(snapshot);
+			const prev = this.lastResourcesEmit;
+			const heartbeatDue = !prev || timestamp - prev.emittedAt >= METRICS_SNAPSHOT_HEARTBEAT_MS;
+			if (!prev || prev.coarse !== coarse || heartbeatDue) {
+				this.lastResourcesEmit = {
+					coarse,
+					emittedAt: timestamp
+				};
+				eventBus.emit(createEvent(EventCategory.MetricsNodeResourcesSnapshot, {
+					type: "node",
+					id: nodeId,
+					nodeId
+				}, {
+					nodeId,
+					snapshot,
+					timestamp
+				}));
+			}
+		} catch {}
+		try {
+			const processes = await this.listNodeProcesses();
+			const coarse = coarsenProcessList(processes);
+			const prev = this.lastProcessesEmit;
+			const heartbeatDue = !prev || timestamp - prev.emittedAt >= METRICS_SNAPSHOT_HEARTBEAT_MS;
+			if (!prev || prev.coarse !== coarse || heartbeatDue) {
+				this.lastProcessesEmit = {
+					coarse,
+					emittedAt: timestamp
+				};
+				eventBus.emit(createEvent(EventCategory.MetricsNodeProcessesSnapshot, {
+					type: "node",
+					id: nodeId,
+					nodeId
+				}, {
+					nodeId,
+					processes,
+					timestamp
+				}));
+			}
+		} catch {}
+	}
+	async onConfigChanged() {
+		this.provider?.stopSampling();
+		this.provider?.startSampling(this.config.samplingIntervalMs);
+	}
+	async listWorkerInstances() {
+		const broker = this.ctx.kernel.cluster?.broker;
+		if (!broker) return [];
+		try {
+			return await broker.call("$process.list");
+		} catch {
+			return [];
+		}
+	}
+	async listAddonInstances() {
+		const hubNodeId = (this.ctx.kernel.cluster?.broker)?.nodeID ?? "hub";
+		const uptimeSec = Math.max(0, Math.floor((Date.now() - this.startedAtMs) / 1e3));
+		const instances = [{
+			addonId: "$hub",
+			nodeId: hubNodeId,
+			role: "hub",
+			pid: process.pid,
+			state: "running",
+			uptimeSec
+		}];
+		const workers = await this.listWorkerInstances();
+		for (const w of workers) instances.push({
+			addonId: w.addonId,
+			nodeId: w.nodeId,
+			role: "worker",
+			pid: w.pid,
+			state: narrowWorkerState(w.state),
+			uptimeSec: w.uptimeSeconds
+		});
+		return instances;
+	}
+	async getAddonStats(addonId) {
+		const provider = this.provider;
+		if (!provider) return null;
+		if (addonId === "$hub") return (await provider.getProcessStats({ pids: [process.pid] }))[0] ?? null;
+		const target = (await this.listWorkerInstances()).find((w) => w.addonId === addonId);
+		if (!target) return null;
+		return (await provider.getProcessStats({ pids: [target.pid] }))[0] ?? null;
+	}
+	/**
+	* Walk the OS process table and classify each camstack-shaped process.
+	*
+	* Classification (ancestry-driven, NOT pattern-driven):
+	*  - root    — the current node's own pid (`process.pid`).
+	*  - managed — pid is registered in the kernel's `$process.list`
+	*              (forked addon worker spawned by this hub).
+	*  - system  — ancestry walk crosses a SUPERVISOR_BOUNDARY_RE match
+	*              (tsx-watch launcher, agent CLI, concurrently, vite,
+	*              npm exec wrapper). The process belongs to the dev
+	*              tree even if not in `$process.list`. NEVER killable.
+	*  - ghost   — ancestry walk reaches `ppid=1` without crossing any
+	*              supervisor boundary AND the parent isn't visible in
+	*              `ps`. A truly orphaned camstack-shaped process. The
+	*              ONLY classification that's eligible for kill.
+	*
+	* Old pattern-only ghost detection produced false positives: every
+	* monorepo-path process matched CAMSTACK_CMD_RE, ancestry walk
+	* stopping at ppid=hub returned false-positive ghosts whenever a
+	* concurrently sibling sat above hub. Ancestry-driven classification
+	* fixes that.
+	*/
+	async listNodeProcesses() {
+		const ps = await this.runPs();
+		if (ps.length === 0) return [];
+		const managedPids = /* @__PURE__ */ new Map();
+		const workers = await this.listWorkerInstances();
+		for (const w of workers) managedPids.set(w.pid, {
+			addonId: w.addonId,
+			nodeId: w.nodeId
+		});
+		const hubNodeId = this.ctx.kernel.cluster?.broker?.nodeID ?? "hub";
+		const selfPid = process.pid;
+		const psIndex = /* @__PURE__ */ new Map();
+		for (const p of ps) psIndex.set(p.pid, {
+			ppid: p.ppid,
+			command: p.command
+		});
+		/**
+		* Walk ancestry from `pid` up to ppid=1 (or until we leave the ps
+		* snapshot). Returns:
+		*   - 'system' — crossed a SUPERVISOR_BOUNDARY_RE ancestor
+		*   - 'ghost'  — reached ppid=1 OR the parent isn't visible in ps
+		*                without crossing a boundary
+		*
+		* `selfPid` itself is treated as a boundary (this node's own root).
+		*/
+		const classifyByAncestry = (startPid) => {
+			let cur = startPid;
+			for (let depth = 0; depth < 32; depth++) {
+				const node = psIndex.get(cur);
+				if (!node) return "ghost";
+				if (cur === selfPid) return "system";
+				if (SUPERVISOR_BOUNDARY_RE.test(node.command)) return "system";
+				if (node.ppid === 1) return "ghost";
+				if (node.ppid === selfPid) return "system";
+				cur = node.ppid;
+			}
+			return "system";
+		};
+		const out = [];
+		for (const p of ps) {
+			if (!CAMSTACK_CMD_RE.test(p.command)) continue;
+			const managed = managedPids.get(p.pid);
+			let classification;
+			if (p.pid === selfPid) classification = "root";
+			else if (managed) classification = "managed";
+			else classification = classifyByAncestry(p.pid);
+			const orphaned = classification === "ghost";
+			out.push({
+				pid: p.pid,
+				ppid: p.ppid,
+				pgid: p.pgid,
+				classification,
+				addonId: managed?.addonId ?? null,
+				nodeId: managed?.nodeId ?? (p.pid === selfPid ? hubNodeId : null),
+				command: p.command,
+				cpuPercent: p.cpuPercent,
+				memoryRssBytes: p.memoryRssBytes,
+				uptimeSec: p.uptimeSec,
+				orphaned
+			});
+		}
+		return out;
+	}
+	/**
+	* Send SIGTERM / SIGKILL to a pid. Refuses pids that don't appear in
+	* `listNodeProcesses()` to prevent arbitrary system kills — a dedicated
+	* admin-path for resurrected zombies, not a generic shell replacement.
+	*
+	* `root`-classified pids (the running launcher / agent CLI / hub itself)
+	* are also refused: killing them tears down the whole node and the
+	* operator's intent is almost always to nuke a leaked child, not the
+	* supervisor that keeps the rest alive. Process restart goes through
+	* the dedicated `$process.restart` action, not this kill API.
+	*/
+	async killProcess(input) {
+		const match = (await this.listNodeProcesses()).find((p) => p.pid === input.pid);
+		if (!match) return {
+			success: false,
+			reason: "pid not in node process table"
+		};
+		if (match.classification === "root" || match.classification === "system") {
+			this.ctx.logger.warn("Refused to kill protected process", { meta: {
+				pid: input.pid,
+				classification: match.classification,
+				addonId: match.addonId,
+				command: match.command
+			} });
+			return {
+				success: false,
+				reason: match.classification === "root" ? "cannot kill root (current node supervisor)" : "cannot kill system (intentional dev-tree ancestor — vite, concurrently, npm, etc.)"
+			};
+		}
+		const signal = input.force ? "SIGKILL" : "SIGTERM";
+		try {
+			process.kill(input.pid, signal);
+			this.ctx.logger.info("Killed node process", { meta: {
+				pid: input.pid,
+				signal,
+				classification: match.classification,
+				addonId: match.addonId
+			} });
+			return {
+				success: true,
+				signal
+			};
+		} catch (err) {
+			return {
+				success: false,
+				reason: err instanceof Error ? err.message : String(err),
+				signal
+			};
+		}
+	}
+	/** Raw `ps` scan returning every pid + command + resource stats. */
+	async runPs() {
+		try {
+			const { stdout } = await execFileAsync("ps", ["-eo", "pid=,ppid=,pgid=,pcpu=,rss=,etime=,command="], {
+				timeout: 5e3,
+				maxBuffer: 8 * 1024 * 1024
+			});
+			const lines = stdout.split("\n");
+			const rows = [];
+			for (const line of lines) {
+				const trimmed = line.trim();
+				if (!trimmed) continue;
+				const match = trimmed.match(/^(\d+)\s+(\d+)\s+(\d+)\s+([\d.]+)\s+(\d+)\s+(\S+)\s+(.+)$/);
+				if (!match) continue;
+				const [, pidS, ppidS, pgidS, cpuS, rssS, etimeS, command] = match;
+				rows.push({
+					pid: parseInt(pidS, 10),
+					ppid: parseInt(ppidS, 10),
+					pgid: parseInt(pgidS, 10),
+					cpuPercent: Math.round(parseFloat(cpuS) * 10) / 10,
+					memoryRssBytes: parseInt(rssS, 10) * 1024,
+					uptimeSec: parseEtime(etimeS),
+					command
+				});
+			}
+			return rows;
+		} catch (err) {
+			this.ctx.logger.warn("ps scan failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return [];
+		}
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: "native-metrics-settings",
+			title: "System Metrics",
+			fields: [this.field({
+				type: "number",
+				key: "samplingIntervalMs",
+				label: "Sampling Interval",
+				description: "How often to collect system metrics",
+				min: 1e3,
+				max: 6e4,
+				step: 1e3,
+				default: 5e3,
+				unit: "ms"
+			})]
+		}] });
+	}
+};
+/**
+* Parse `ps etime` format → seconds.
+*
+* Formats we handle:
+*  `MM:SS`           (< 1h)
+*  `HH:MM:SS`        (< 1d)
+*  `DD-HH:MM:SS`     (>= 1d)
+*/
+function parseEtime(etime) {
+	const dashParts = etime.split("-");
+	let days = 0;
+	let hms = etime;
+	if (dashParts.length === 2) {
+		days = parseInt(dashParts[0], 10) || 0;
+		hms = dashParts[1];
+	}
+	const parts = hms.split(":").map((p) => parseInt(p, 10) || 0);
+	let hours = 0, minutes = 0, seconds = 0;
+	if (parts.length === 3) [hours, minutes, seconds] = parts;
+	else if (parts.length === 2) [minutes, seconds] = parts;
+	else if (parts.length === 1) [seconds] = parts;
+	return days * 86400 + hours * 3600 + minutes * 60 + seconds;
+}
+//#endregion
+export { NativeMetricsAddon as default, NativeMetricsProvider as t };
+
 //# sourceMappingURL=native-metrics.addon.mjs.map