BREAKING CHANGE(smartmetrics): add system-wide metrics collection, Prometheus gauges, and normalized CPU reporting

ts/smartmetrics.pidusage.ts

@@ -1,6 +1,12 @@
 import * as fs from 'fs';
+import * as os from 'os';
 import { execSync } from 'child_process';
 
+// CPU core count (cached at module load)
+const cpuCoreCount = typeof os.availableParallelism === 'function'
+  ? os.availableParallelism()
+  : os.cpus().length;
+
 // Cached system constants
 let clkTck: number | null = null;
 let pageSize: number | null = null;
@@ -61,8 +67,10 @@ function hrtimeSeconds(): number {
 }
 
 export interface IPidUsageResult {
-  cpu: number;
-  memory: number;
+  cpu: number;                  // raw per-core CPU% (can exceed 100%)
+  cpuCoreCount: number;         // number of CPU cores on the machine
+  cpuNormalizedPercent: number;  // cpu / coreCount — 0-100% of total machine
+  memory: number;               // RSS in bytes
 }
 
 /**
@@ -95,12 +103,16 @@ export async function getPidUsage(
 
       result[pid] = {
         cpu: cpuPercent,
+        cpuCoreCount,
+        cpuNormalizedPercent: cpuPercent / cpuCoreCount,
         memory: memoryBytes,
       };
     } else {
       // First call for this PID — no delta available, report 0% cpu
       result[pid] = {
         cpu: 0,
+        cpuCoreCount,
+        cpuNormalizedPercent: 0,
         memory: memoryBytes,
       };
     }