@hienlh/ppm 0.18.7 → 0.18.9

package/src/server/routes/resources.ts

@@ -1,88 +1,134 @@
+/**
+ * Whole-machine metrics routes, mounted under `/api/system` behind auth.
+ *
+ *   GET    /resources?processes=0|1          latest snapshot for that tier (or null)
+ *   GET    /resources/stream?processes=0|1   SSE: `session` frame, then `snapshot` frames
+ *   POST   /resources/stream/:sid/ping       renew the subscriber lease
+ *   DELETE /resources/stream/:sid            drop the subscriber
+ *   POST   /resources/kill                   guarded kill (JSON + X-PPM-Request header)
+ */
 import { Hono } from "hono";
-import { resourceMonitor, type ResourceSnapshot } from "../../services/resource-monitor.service.ts";
+import type { MetricsSnapshot, MetricsTier } from "../../types/system-metrics.ts";
 import { ok, err } from "../../types/api.ts";
+import {
+  systemMetricsService, MAX_STREAM_SUBSCRIBERS, type SystemMetricsService,
+} from "../../services/system-metrics/system-metrics.service.ts";
+import { isValidSid } from "../../services/system-metrics/metrics-subscriber-registry.ts";
 
-export const resourceRoutes = new Hono();
+/** Frames a stalled client failed to take before the stream is closed. Metrics
+ *  are lossy by nature; `ReadableStream`'s queue is not, and 30-60 KB every 2 s
+ *  toward a dead mobile client is ~54 MB/hour of heap. */
+export const MAX_DROPPED_FRAMES = 10;
 
-const MAX_SSE_CLIENTS = 5;
-let sseClientCount = 0;
+const tierOf = (raw: string | undefined): MetricsTier => (raw === "1" || raw === "true" ? "full" : "light");
 
-/** GET /resources — latest snapshot as JSON */
-resourceRoutes.get("/resources", (c) => {
-  return c.json(ok(resourceMonitor.getLatest()));
-});
+export function createResourceRoutes(service: SystemMetricsService = systemMetricsService): Hono {
+  const routes = new Hono();
 
-/** GET /resources/history — full ring buffer */
-resourceRoutes.get("/resources/history", (c) => {
-  return c.json(ok(resourceMonitor.getHistory()));
-});
+  routes.get("/resources", (c) => c.json(ok(service.getLatest(tierOf(c.req.query("processes"))))));
 
-/** POST /resources/kill/:pid — send SIGTERM to a process in PPM's tree */
-resourceRoutes.post("/resources/kill/:pid", async (c) => {
-  const pid = parseInt(c.req.param("pid"), 10);
-  if (isNaN(pid) || pid <= 0) {
-    return c.json(err("Invalid PID"), 400);
-  }
-  // Safety: only allow killing processes in PPM's own tree
-  const snapshot = resourceMonitor.getLatest();
-  if (!snapshot) {
-    return c.json(err("No resource data available"), 400);
-  }
-  const allPids = snapshot.groups.flatMap((g) => g.processes.map((p) => p.pid));
-  if (!allPids.includes(pid)) {
-    return c.json(err("PID not in PPM process tree"), 403);
-  }
-  // Don't allow killing the server itself
-  if (pid === process.pid) {
-    return c.json(err("Cannot kill PPM server process"), 403);
-  }
-  try {
-    process.kill(pid, "SIGTERM");
-    return c.json(ok({ pid, signal: "SIGTERM" }));
-  } catch (e: any) {
-    return c.json(err(`Failed to kill PID ${pid}: ${e.message}`), 500);
-  }
-});
+  routes.get("/resources/stream", (c) => {
+    const tier = tierOf(c.req.query("processes"));
+    // A 429 is only possible before the body starts, so reap expired leases and
+    // check the cap here — BEFORE the stream is built, because `start()` runs
+    // synchronously at construction. subscribe() re-checks in case two opens race.
+    service.reapExpired();
+    if (service.liveCount() >= MAX_STREAM_SUBSCRIBERS) {
+      return c.json(err("Too many metrics subscribers"), 429);
+    }
 
-/** GET /resources/stream — SSE stream of snapshots every 3s */
-resourceRoutes.get("/resources/stream", (c) => {
-  if (sseClientCount >= MAX_SSE_CLIENTS) {
-    return c.json({ ok: false, error: "Too many SSE clients" }, 429);
-  }
+    const encoder = new TextEncoder();
+    let sid: string | null = null;
+    let drops = 0;
 
-  let callbackRef: ((s: ResourceSnapshot) => void) | null = null;
-
-  const stream = new ReadableStream({
-    start(controller) {
-      sseClientCount++;
-      const encoder = new TextEncoder();
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        const close = () => { try { controller.close(); } catch { /* already closed */ } };
+        const result = service.subscribe({
+          tier,
+          close,
+          deliver: (snapshot: MetricsSnapshot) => {
+            // `enqueue` never throws on backpressure, only on a closed controller,
+            // so `desiredSize` is the only signal that the client stopped reading.
+            if ((controller.desiredSize ?? 1) <= 0) {
+              if (++drops >= MAX_DROPPED_FRAMES) {
+                if (sid) service.unsubscribe(sid);
+                close();
+              }
+              return;
+            }
+            drops = 0;
+            try {
+              controller.enqueue(encoder.encode(`event: snapshot\ndata: ${JSON.stringify(snapshot)}\n\n`));
+            } catch {
+              if (sid) service.unsubscribe(sid);
+            }
+          },
+        });
+        if (!result) {
+          controller.enqueue(encoder.encode(`event: error\ndata: ${JSON.stringify({ error: "Too many metrics subscribers" })}\n\n`));
+          close();
+          return;
+        }
+        sid = result.sid;
+        controller.enqueue(encoder.encode("retry: 5000\n\n"));
+        controller.enqueue(encoder.encode(`event: session\ndata: ${JSON.stringify(result)}\n\n`));
+      },
+      cancel() {
+        // Best effort only — a proxy may keep this request alive after the
+        // browser left, which is what the lease + DELETE route are for.
+        if (sid) service.unsubscribe(sid);
+      },
+    });
 
-      // Send retry hint for reconnect interval
-      controller.enqueue(encoder.encode("retry: 5000\n\n"));
+    return new Response(stream, {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+      },
+    });
+  });
 
-      callbackRef = (snapshot: ResourceSnapshot) => {
-        try {
-          const data = `event: snapshot\ndata: ${JSON.stringify(snapshot)}\n\n`;
-          controller.enqueue(encoder.encode(data));
-        } catch {
-          // Client disconnected — cleanup happens in cancel
-        }
-      };
+  routes.post("/resources/stream/:sid/ping", (c) => {
+    const sid = c.req.param("sid");
+    if (!isValidSid(sid) || !service.ping(sid)) return c.json(err("Unknown or expired stream session"), 404);
+    return c.json(ok({ alive: true }));
+  });
 
-      resourceMonitor.subscribe(callbackRef);
-    },
-    cancel() {
-      sseClientCount = Math.max(0, sseClientCount - 1);
-      if (callbackRef) resourceMonitor.unsubscribe(callbackRef);
-      callbackRef = null;
-    },
+  routes.delete("/resources/stream/:sid", (c) => {
+    const sid = c.req.param("sid");
+    const stopped = isValidSid(sid) ? service.unsubscribe(sid) : false;
+    return c.json(ok({ stopped }));
   });
 
-  return new Response(stream, {
-    headers: {
-      "Content-Type": "text/event-stream",
-      "Cache-Control": "no-cache",
-      "Connection": "keep-alive",
-    },
+  routes.post("/resources/kill", async (c) => {
+    // CSRF hardening for the auth-disabled configuration: a cross-origin HTML
+    // form can set neither a JSON content type nor a custom header, so both
+    // force a preflight that the browser will refuse.
+    const contentType = c.req.header("content-type") ?? "";
+    if (!contentType.toLowerCase().startsWith("application/json")) {
+      return c.json(err("Content-Type must be application/json"), 400);
+    }
+    if (c.req.header("x-ppm-request") !== "1") return c.json(err("Missing X-PPM-Request header"), 400);
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json(err("Invalid JSON body"), 400);
+    }
+    try {
+      const outcome = await service.kill(body);
+      return c.json(outcome.body, outcome.status);
+    } catch (e) {
+      // The live re-query itself failed (collector down, session restarting);
+      // nothing was signalled, so the client can simply retry.
+      console.error("[SystemMetrics] kill re-query failed:", (e as Error)?.message ?? e);
+      return c.json(err("Could not verify the process — try again"), 500);
+    }
   });
-});
+
+  return routes;
+}
+
+export const resourceRoutes = createResourceRoutes();

package/src/services/autostart-generator.ts

@@ -205,18 +205,90 @@ export function buildRegDeleteCommand(): string[] {
 // by third-party "startup cleaner" utilities that only target Run keys and
 // the Startup folder. No admin required for a current-user logon task.
 
-/** wscript runs the VBS without a console window; VBS in turn launches bun hidden. */
-function buildTaskRunString(vbsPath: string): string {
-  return `wscript.exe "${vbsPath}"`;
+/**
+ * The account the task runs as, and whose logon fires it — `DOMAIN\user`, or
+ * bare user name when the machine reports no domain.
+ */
+export function getCurrentWindowsUserId(): string {
+  const user = process.env.USERNAME ?? "";
+  const domain = process.env.USERDOMAIN ?? process.env.COMPUTERNAME ?? "";
+  return domain ? `${domain}\\${user}` : user;
+}
+
+export function getTaskXmlPath(): string {
+  return resolve(homedir(), ".ppm", "ppm-task.xml");
+}
+
+/**
+ * Task Scheduler XML for the At-logon task.
+ *
+ * `schtasks /SC ONLOGON` cannot express *which* user's logon fires the task:
+ * it always emits a LogonTrigger with no UserId, meaning "any user logs on",
+ * and registering that is an all-users change the Task Scheduler refuses for a
+ * standard account — the create fails with "ERROR: Access is denied." even
+ * when /RU names the caller, because /RU sets the run-as principal, not the
+ * trigger scope. Registering from XML lets the trigger carry a UserId, which
+ * scopes it to this account and needs no elevation.
+ *
+ * ExecutionTimeLimit must be PT0S (unlimited): schtasks would have defaulted to
+ * PT72H and killed the supervisor after three days of uptime.
+ */
+export function generateTaskXml(vbsPath: string, userId = getCurrentWindowsUserId()): string {
+  const user = escapeXml(userId);
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>PPM - starts the PPM supervisor at logon</Description>
+    <URI>\\${TASK_NAME}</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${user}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${user}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>false</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>wscript.exe</Command>
+      <Arguments>"${escapeXml(vbsPath)}"</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
 }
 
-/** Build schtasks command to create the At-logon task (no admin) */
-export function buildSchtasksCreateCommand(vbsPath: string): string[] {
+/** Build schtasks command to create the At-logon task from XML (no admin) */
+export function buildSchtasksCreateCommand(xmlPath: string): string[] {
   return [
     "schtasks", "/Create",
     "/TN", TASK_NAME,
-    "/TR", buildTaskRunString(vbsPath),
-    "/SC", "ONLOGON",
+    "/XML", xmlPath,
     "/F",
   ];
 }

package/src/services/autostart-register.ts

@@ -11,6 +11,8 @@ import {
   getServicePath,
   generateVbsWrapper,
   getVbsPath,
+  generateTaskXml,
+  getTaskXmlPath,
   buildRegDeleteCommand,
   buildSchtasksCreateCommand,
   buildSchtasksDeleteCommand,
@@ -300,18 +302,27 @@ function statusLinux(): AutoStartStatus {
 
 async function enableWindows(config: AutoStartConfig): Promise<string> {
   const vbsPath = getVbsPath();
+  const xmlPath = getTaskXmlPath();
   const vbsDir = dirname(vbsPath);
 
   if (!existsSync(vbsDir)) mkdirSync(vbsDir, { recursive: true });
   writeFileSync(vbsPath, generateVbsWrapper(config));
 
+  // Task Scheduler only accepts a definition file encoded as UTF-16 and reads
+  // the BOM to detect it; a UTF-8 file is rejected as malformed XML.
+  writeFileSync(xmlPath, `\ufeff${generateTaskXml(vbsPath)}`, "utf16le");
+
   // Register an At-logon scheduled task (no admin). More reliable than the
   // HKCU Run key, which startup-cleaner utilities sweep and which can silently
   // fail to fire at logon.
-  const cmd = buildSchtasksCreateCommand(vbsPath);
+  const cmd = buildSchtasksCreateCommand(xmlPath);
   const result = Bun.spawnSync({ cmd, stdout: "pipe", stderr: "pipe" });
 
   if (result.exitCode !== 0) {
+    // Leave nothing half-registered: a stale wrapper and definition on disk
+    // make the next `ppm autostart status` look configured when no task exists.
+    try { unlinkSync(vbsPath); } catch {}
+    try { unlinkSync(xmlPath); } catch {}
     const err = result.stderr.toString().trim() || result.stdout.toString().trim();
     throw new Error(`schtasks create failed: ${err}`);
   }
@@ -336,9 +347,11 @@ async function disableWindows(): Promise<void> {
   Bun.spawnSync({ cmd: buildSchtasksDeleteCommand(), stdout: "ignore", stderr: "ignore" });
   Bun.spawnSync({ cmd: buildRegDeleteCommand(), stdout: "ignore", stderr: "ignore" });
 
-  // Remove VBS wrapper
+  // Remove VBS wrapper and task definition
   const vbsPath = getVbsPath();
   try { if (existsSync(vbsPath)) unlinkSync(vbsPath); } catch {}
+  const xmlPath = getTaskXmlPath();
+  try { if (existsSync(xmlPath)) unlinkSync(xmlPath); } catch {}
 
   removeMetadata();
 }

package/src/services/fs-path-guard.service.ts

@@ -2,6 +2,7 @@ import { resolve, sep } from "node:path";
 import { lstat, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { getPpmDir } from "./ppm-dir.ts";
+import { getUploadsDir } from "./chat-upload-storage.service.ts";
 import { realPathOrSelf, realPathOrSelfSync } from "./fs-ops/fs-real-path.ts";
 
 // Re-exported so callers reach both the guards and the resolver they build on
@@ -84,13 +85,28 @@ export function isPpmDirPath(resolved: string): boolean {
   return isInside(resolved, getPpmDir());
 }
 
+/**
+ * Chat attachments the user uploaded through the UI. They sit under the PPM
+ * dir so chat history keeps resolving them across reboots, but they are
+ * ordinary user content, not credential material: the transcript has to render
+ * the very image the assistant just read back from that directory.
+ */
+export function isChatUploadPath(resolved: string): boolean {
+  return isInside(resolved, getUploadsDir());
+}
+
 /**
  * Refuse the PPM directory subtree on read-style doors. It stores the config
  * database with provider credentials and auth tokens, which must never be
  * downloadable through a generic file route.
+ *
+ * Chat uploads are the one exception. Every caller applies this to the
+ * requested path *and* to its real path, so a symlink parked in the uploads
+ * directory still fails on the second call and cannot reach the rest of the
+ * PPM dir through the exception.
  */
 export function assertNotPpmDir(resolved: string): void {
-  if (isPpmDirPath(resolved)) {
+  if (isPpmDirPath(resolved) && !isChatUploadPath(resolved)) {
     throw Object.assign(new Error("Access denied"), { status: 403, code: "EDENIED" });
   }
 }

package/src/services/media-transcode/transcode-stream.ts

@@ -8,21 +8,36 @@
  * by re-requesting with `start`, which becomes `-ss` *before* `-i` (fast keyframe
  * seek; exact-frame seeking would decode from the file start every time).
  *
- * Every spawned process is tied to the response body: when the browser drops the
- * connection (tab closed, seek, next file) the stream is cancelled and only that PID
- * is killed — never a blanket kill by image name.
+ * Process lifetime is controlled explicitly, not only by the connection: a job is
+ * keyed by the player's `sessionId`, a new request for the same session kills the
+ * previous job, and the player sends a stop when it unmounts. Relying on the client
+ * disconnect alone is not enough — Cloudflare Tunnel (and other proxies) keep the
+ * origin request open and drain the body after the browser has gone, which left
+ * every seek's ffmpeg running to the end of the file and exhausted the job slots.
+ * Only the job's own PID is ever killed — never a blanket kill by image name.
  */
 import { encoderArgs, getFfmpegCapabilities } from "./ffmpeg-capabilities.ts";
 
-/** Parallel ffmpeg jobs allowed. A seek briefly overlaps old + new job, so allow a little slack. */
-export const MAX_CONCURRENT_TRANSCODES = 3;
+/** Parallel ffmpeg jobs allowed across all players (one per player after session replacement). */
+export const MAX_CONCURRENT_TRANSCODES = 4;
 let active = 0;
 
+/** Live jobs by player session so a seek or unmount can stop the right one. */
+const jobsBySession = new Map<string, () => void>();
+
 /** How many transcodes are running right now (exposed for tests/diagnostics). */
 export function activeTranscodeCount(): number {
   return active;
 }
 
+/** Kill the job a player owns. Returns false when nothing was running for it. */
+export function stopTranscode(sessionId: string): boolean {
+  const kill = jobsBySession.get(sessionId);
+  if (!kill) return false;
+  kill();
+  return true;
+}
+
 export class TranscodeUnavailableError extends Error {
   constructor(msg = "ffmpeg is not installed or has no working H.264 encoder") {
     super(msg);
@@ -42,6 +57,8 @@ export interface TranscodeOptions {
   start?: number;
   /** Aborts the job when the HTTP request is aborted. */
   signal?: AbortSignal;
+  /** Player instance id; a new job for the same id replaces (kills) the previous one. */
+  sessionId?: string;
 }
 
 /** Build the ffmpeg argv; pure so tests can assert on it without spawning. */
@@ -72,6 +89,8 @@ export interface TranscodeJob {
 export async function startTranscode(absPath: string, opts: TranscodeOptions = {}): Promise<TranscodeJob> {
   const caps = await getFfmpegCapabilities();
   if (!caps.ffmpeg || !caps.encoder) throw new TranscodeUnavailableError();
+  // A seek is a replacement, not an addition: free this player's slot before counting.
+  if (opts.sessionId) stopTranscode(opts.sessionId);
   if (active >= MAX_CONCURRENT_TRANSCODES) throw new TranscodeBusyError();
 
   const proc = Bun.spawn(buildTranscodeArgs(caps.ffmpeg, absPath, caps.encoder, opts.start), {
@@ -85,6 +104,8 @@ export async function startTranscode(absPath: string, opts: TranscodeOptions = {
     if (finished) return;
     finished = true;
     active--;
+    // Only drop the registration if it is still ours — a replacement may already own the key.
+    if (opts.sessionId && jobsBySession.get(opts.sessionId) === kill) jobsBySession.delete(opts.sessionId);
   };
 
   // Drain stderr so ffmpeg never blocks on a full pipe; keep the tail for the log.
@@ -102,6 +123,7 @@ export async function startTranscode(absPath: string, opts: TranscodeOptions = {
     finish();
   };
   opts.signal?.addEventListener("abort", kill, { once: true });
+  if (opts.sessionId) jobsBySession.set(opts.sessionId, kill);
 
   // Wrap stdout so a cancelled response body (client went away) kills this process.
   //

package/src/services/proc-table-linux.ts

@@ -28,6 +28,9 @@ export interface ProcEntry {
   ppid: number;
   /** Average CPU% over the process lifetime — the same figure `ps %cpu` prints. */
   cpuPercent: number;
+  /** Cumulative CPU time (utime + stime), milliseconds. Diff two reads for an
+   *  instantaneous figure — `cpuPercent` is a lifetime average and never moves. */
+  cpuMs: number;
   rssKB: number;
   /** Seconds since the process started. */
   elapsedSec: number;
@@ -121,6 +124,7 @@ export function readProcTable(): ProcEntry[] | null {
       pid,
       ppid: f.ppid,
       cpuPercent: Math.round((cpuSec / elapsedSec) * 1000) / 10,
+      cpuMs: cpuSec * 1000,
       rssKB: f.rssPages * PAGE_SIZE_KB,
       elapsedSec,
       startedAtMs: bootTimeMs + startSec * 1000,

package/src/services/redact-secrets.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared secret redactor for text that leaves the server: the public
+ * `/api/logs/recent` tail and process command lines in the metrics stream.
+ *
+ * Kept in one place so both consumers agree on what counts as a secret. Apply
+ * it BEFORE any truncation — secrets sit at the front of argv (`--token=…`,
+ * `postgres://user:pass@…`, `ANTHROPIC_API_KEY=… node x.js`), so truncating
+ * first would keep the secret and leave the redactor nothing to find.
+ *
+ * Rules: the six log-line forms (`Token: x`, `Bearer x`, `password: x`,
+ * `api_key: x`, `ANTHROPIC_API_KEY=x`, `secret: x`), then the argv forms —
+ * `key=value`, `--key value`, and URL userinfo `scheme://user:pass@host`.
+ */
+const RULES: ReadonlyArray<[RegExp, string]> = [
+  [/Token:\s*\S+/gi, "Token: [REDACTED]"],
+  [/Bearer\s+\S+/gi, "Bearer [REDACTED]"],
+  [/password['":\s]+\S+/gi, "password: [REDACTED]"],
+  [/api[_-]?key['":\s]+\S+/gi, "api_key: [REDACTED]"],
+  [/ANTHROPIC_API_KEY=\S+/gi, "ANTHROPIC_API_KEY=[REDACTED]"],
+  [/secret['":\s]+\S+/gi, "secret: [REDACTED]"],
+  // argv `--token=abc`, `API_KEY=abc`, `DB_PASSWORD=abc`.
+  [/((?:token|api[_-]?key|secret|password)=)\S+/gi, "$1[REDACTED]"],
+  // argv space form `--token abc`, `-p abc` is too ambiguous and is left alone.
+  [/(--?(?:token|api[_-]?key|secret|password)\s+)\S+/gi, "$1[REDACTED]"],
+  // URL userinfo `postgres://user:pass@host` → keep the user, drop the password.
+  [/(:\/\/[^/\s:@]+:)[^@\s]+@/g, "$1[REDACTED]@"],
+];
+
+export function redactSecrets(text: string): string {
+  let out = text;
+  for (const [re, replacement] of RULES) out = out.replace(re, replacement);
+  return out;
+}

package/src/services/system-metrics/cpu-memory-collector.ts

@@ -0,0 +1,101 @@
+/**
+ * Whole-machine CPU + memory from `node:os`. Runs in both tiers, spawns nothing.
+ */
+import os from "node:os";
+import { readFileSync } from "node:fs";
+import type { CpuMetrics, MemoryMetrics } from "../../types/system-metrics.ts";
+
+export interface CoreTimes {
+  user: number;
+  nice: number;
+  sys: number;
+  idle: number;
+  irq: number;
+}
+
+export interface CpuTimesSample {
+  times: CoreTimes[];
+  /** Wall clock of the sample, epoch ms. */
+  at: number;
+  model: string;
+}
+
+/**
+ * Read `os.cpus()` and copy the numbers out immediately. Bun 1.3.10 on Windows
+ * returns the SAME `times` on a later call while the array from the previous
+ * call is still referenced — the delta then reads 0 % forever, with no error
+ * anywhere. Keeping only plain copies between ticks avoids it.
+ */
+export function sampleCpuTimes(now: number = Date.now()): CpuTimesSample {
+  const cpus = os.cpus();
+  const times = cpus.map((c) => ({ ...c.times }));
+  return { times, at: now, model: cpus[0]?.model?.trim() ?? "" };
+}
+
+const round1 = (n: number): number => Math.round(n * 10) / 10;
+
+/** Busy % total + per core between two samples. Pure. First sample → all zeros. */
+export function computeCpuFromSamples(prev: CpuTimesSample | null, next: CpuTimesSample): CpuMetrics {
+  const zeros: CpuMetrics = { total: 0, cores: next.times.map(() => 0), model: next.model };
+  if (!prev || prev.times.length !== next.times.length) return zeros;
+
+  let busySum = 0;
+  let totalSum = 0;
+  const cores = next.times.map((n, i) => {
+    const p = prev.times[i]!;
+    const idle = n.idle - p.idle;
+    const total = (n.user - p.user) + (n.nice - p.nice) + (n.sys - p.sys) + idle + (n.irq - p.irq);
+    if (!(total > 0)) return 0;
+    busySum += total - idle;
+    totalSum += total;
+    return clampPercent((total - idle) / total * 100);
+  });
+  const total = totalSum > 0 ? clampPercent(busySum / totalSum * 100) : 0;
+  return { total, cores, model: next.model };
+}
+
+function clampPercent(v: number): number {
+  if (!Number.isFinite(v)) return 0;
+  return round1(Math.min(100, Math.max(0, v)));
+}
+
+/** Read `/proc/meminfo` on Linux, null elsewhere or on failure. Injectable for tests. */
+export function readMeminfo(): string | null {
+  if (process.platform !== "linux") return null;
+  try {
+    return readFileSync("/proc/meminfo", "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** `MemAvailable` in bytes from a `/proc/meminfo` dump, or null when absent. */
+export function parseMemAvailableBytes(meminfo: string): number | null {
+  const m = /^MemAvailable:\s+(\d+)\s*kB/m.exec(meminfo);
+  if (!m) return null;
+  const kb = Number(m[1]);
+  return Number.isFinite(kb) ? kb * 1024 : null;
+}
+
+/**
+ * `os.totalmem()` matches `Win32_OperatingSystem.TotalVisibleMemorySize` exactly
+ * and `os.freemem()` is within 0.2 GiB of CIM's `FreePhysicalMemory`. On Linux
+ * `freemem()` is `MemFree`, which makes a warm page cache look like a nearly
+ * full machine — `MemAvailable` is what `free` and Task-Manager-like tools show.
+ */
+export function collectMemory(meminfo: () => string | null = readMeminfo): MemoryMetrics {
+  const totalBytes = os.totalmem();
+  let availableBytes = os.freemem();
+  const info = meminfo();
+  if (info) {
+    const avail = parseMemAvailableBytes(info);
+    if (avail !== null) availableBytes = avail;
+  }
+  availableBytes = Math.min(Math.max(availableBytes, 0), totalBytes);
+  const MB = 1024 * 1024;
+  const totalMB = round1(totalBytes / MB);
+  const availableMB = round1(availableBytes / MB);
+  const usedMB = round1(Math.max(totalMB - availableMB, 0));
+  const percent = totalMB > 0 ? round1(usedMB / totalMB * 100) : 0;
+  return { totalMB, usedMB, availableMB, percent };
+}