@hienlh/ppm 0.23.20 → 0.23.22

package/src/services/memory-diagnostics-requests.ts

@@ -0,0 +1,95 @@
+/**
+ * Counts HTTP requests by route for the memory monitor, so growth can be put next to traffic.
+ *
+ * The server's 26/10/2026 leak kept about a file's size of native memory per *file response*
+ * and per transcript read. Spawn counts could not show that: it rose with requests, not with
+ * child processes. A per-route count and the bytes each route sent, logged beside private
+ * bytes, is what lets the next reader say "it grows by N MB per `/api/files/raw`".
+ *
+ * Counters are cumulative; each reader keeps its own previous copy and diffs (`diffRequestCounts`),
+ * because the 30-second monitor and the 30-minute summary read the same counters at different rates.
+ *
+ * A route key is the method plus the path with anything that is data — a project name, an id,
+ * a file path, a token — replaced by a placeholder, so the log never carries one.
+ */
+
+export interface RouteCount {
+  count: number;
+  /** Bytes declared by `Content-Length`; a streamed body has none and is counted in `streamed`. */
+  bytes: number;
+  streamed: number;
+}
+
+/** Segments after which the next one is a name or a token, never a route word. */
+const NAME_BEFORE = new Set(["project", "projects", "session", "sessions", "content", "grid-export", "whep", "designs", "accounts", "connections", "extensions"]);
+/** A segment that reads as a route word rather than data. */
+const ROUTE_WORD = /^[a-z][a-z0-9-]{0,30}$/;
+const MAX_SEGMENTS = 4;
+/** Distinct keys kept; a path pattern we failed to normalise must not grow the map forever. */
+const MAX_KEYS = 500;
+
+/** `GET /api/project/ppm/files/raw?path=…` → `GET /api/project/:name/files`. Exported for tests. */
+export function requestRouteKey(method: string, pathname: string): string {
+  const segs = pathname.split("/").filter(Boolean);
+  if (segs[0] !== "api" && segs[0] !== "ws") {
+    const ext = pathname.match(/\.([a-z0-9]{1,8})$/i)?.[1]?.toLowerCase();
+    return `${method} static${ext ? ` .${ext}` : ""}`;
+  }
+  const out: string[] = [];
+  for (let i = 0; i < segs.length && out.length < MAX_SEGMENTS; i++) {
+    const seg = segs[i]!;
+    const prev = segs[i - 1];
+    if (prev && NAME_BEFORE.has(prev)) out.push(":name");
+    else out.push(ROUTE_WORD.test(seg) ? seg : ":x");
+  }
+  return `${method} /${out.join("/")}`;
+}
+
+export class RequestTracker {
+  private readonly counts = new Map<string, RouteCount>();
+  private total = 0;
+
+  record(method: string, pathname: string, contentLength: string | null): void {
+    this.total++;
+    const key = requestRouteKey(method, pathname);
+    let entry = this.counts.get(key);
+    if (!entry) {
+      if (this.counts.size >= MAX_KEYS) return;
+      entry = { count: 0, bytes: 0, streamed: 0 };
+      this.counts.set(key, entry);
+    }
+    entry.count++;
+    const n = contentLength === null ? NaN : Number(contentLength);
+    if (Number.isFinite(n)) entry.bytes += n; else entry.streamed++;
+  }
+
+  /** A copy of the cumulative counters. */
+  read(): { total: number; routes: Map<string, RouteCount> } {
+    const routes = new Map<string, RouteCount>();
+    for (const [k, v] of this.counts) routes.set(k, { ...v });
+    return { total: this.total, routes };
+  }
+}
+
+/** What happened between two readings: the busiest routes, by count, with MB sent. */
+export function diffRequestCounts(
+  prev: ReturnType<RequestTracker["read"]> | undefined,
+  now: ReturnType<RequestTracker["read"]>,
+  limit: number,
+): { total: number; top: Record<string, { n: number; mb: number; streamed: number }> } {
+  const rows: Array<[string, number, number, number]> = [];
+  for (const [key, v] of now.routes) {
+    const p = prev?.routes.get(key);
+    const n = v.count - (p?.count ?? 0);
+    if (n <= 0) continue;
+    rows.push([key, n, v.bytes - (p?.bytes ?? 0), v.streamed - (p?.streamed ?? 0)]);
+  }
+  rows.sort((a, b) => b[1] - a[1]);
+  const top: Record<string, { n: number; mb: number; streamed: number }> = {};
+  for (const [key, n, bytes, streamed] of rows.slice(0, limit)) {
+    top[key] = { n, mb: Math.round((bytes / (1024 * 1024)) * 10) / 10, streamed };
+  }
+  return { total: now.total - (prev?.total ?? 0), top };
+}
+
+export const requestTracker = new RequestTracker();

package/src/services/memory-diagnostics-spawns.ts

@@ -0,0 +1,242 @@
+/**
+ * Counts every child process the server starts, for the memory monitor.
+ *
+ * A child process is the prime suspect for native growth on Windows: each
+ * `powershell.exe` spawn was measured to cost Bun a 32 MiB allocator segment it never
+ * returns (see `system-metrics/powershell-session.ts`). A per-interval count by command,
+ * logged beside private bytes, is what lets a later reader say "the commit charge climbs
+ * by N MB per `git` spawn" instead of guessing.
+ *
+ * It wraps `Bun.spawn` and `Bun.spawnSync`, which is enough: in Bun, `node:child_process`
+ * (`spawn`, `exec`, `execFile`, and their sync forms — what the Claude SDK, simple-git and
+ * codex go through) is built on those two globals, so the wrapper sees them too. Only a
+ * module that saved its own reference to `Bun.spawn` before the wrapper went in is missed.
+ *
+ * A label is the program's basename plus at most one more word that is known not to be data:
+ * a git subcommand, a script file's name, a runner's own subcommand, or the first program a
+ * shell is told to run. Anything else — an inline script, an argument, a word carrying `=`,
+ * `$` or quotes — is left out, because an argument can be a path, a prompt or a token.
+ */
+
+interface LiveChild {
+  pid: number;
+  label: string;
+  startedAt: number;
+  /** The chat session a Claude/Codex subprocess serves, from its own `--resume`/`--session-id`. */
+  session?: string;
+  /** Private bytes the last time the tree was read, so an exit can say what the child held. */
+  lastPrivateMB?: number;
+}
+
+/** What a long-lived child's start and exit look like to whoever logs them. */
+export interface ChildLifecycleEvent {
+  event: "start" | "exit";
+  pid: number;
+  label: string;
+  session?: string;
+  ageMin?: number;
+  lastPrivateMB?: number;
+}
+
+/** Labels whose start and exit are worth a log line: few, long-lived, and each one is a chat. */
+const LIFECYCLE_LABEL = /^(claude|codex)\b/;
+/** Session ids are UUIDs; anything else after the flag is not taken. */
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SESSION_FLAGS = ["--resume", "--session-id"];
+
+/** The session a command line resumes or names, when it carries one. Exported for tests. */
+export function sessionOf(argv: readonly unknown[]): string | undefined {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (typeof a !== "string") continue;
+    for (const flag of SESSION_FLAGS) {
+      const value = a === flag ? argv[i + 1] : a.startsWith(`${flag}=`) ? a.slice(flag.length + 1) : undefined;
+      if (typeof value === "string" && SESSION_ID.test(value)) return value;
+    }
+  }
+  return undefined;
+}
+
+export interface SpawnSnapshot {
+  /** Spawns since the previous snapshot, by label (sync ones included). */
+  spawned: Record<string, number>;
+  /** Children still running now, by label. */
+  live: Record<string, number>;
+  liveTotal: number;
+  /** Every spawn since the tracker started. */
+  total: number;
+}
+
+/** Programs whose own name says nothing: the script or subcommand after them is the label. */
+const RUNNERS = new Set(["node", "bun", "npx", "bunx", "python", "python3", "py", "deno"]);
+/** Programs handed a whole command line as one argument. */
+const SHELLS = new Set(["cmd", "powershell", "pwsh", "sh", "bash", "zsh"]);
+/** A runner flag whose value is code to run: the label stops at the flag. */
+const EVAL_FLAGS = new Set(["-e", "--eval", "-p", "--print", "-c"]);
+/** A runner's own subcommands, which are words and never data. */
+const RUNNER_SUBCOMMANDS = new Set(["run", "x", "exec", "install", "add", "remove", "test", "build", "upgrade"]);
+/** Runner flags that take a separate value, which is not the script. */
+const RUNNER_VALUE_FLAGS = new Set(["-r", "--require", "--import", "--loader", "--cwd", "--env-file", "--config", "-m"]);
+/** The shell flag after which the command line comes. */
+const SHELL_COMMAND_FLAGS = new Set(["-c", "/c", "/k", "-command", "-file"]);
+const SCRIPT_FILE = /\.(c|m)?[jt]sx?$|\.py$|\.ps1$/i;
+/** A word that is plausibly a program or subcommand name and cannot carry an assignment or a quote. */
+const PLAIN_WORD = /^[A-Za-z0-9._\\/:@+-]+$/;
+const GIT_VALUE_FLAGS = new Set(["-c", "-C", "--git-dir", "--work-tree", "--namespace", "--exec-path"]);
+
+/** Lowercased basename with the executable extension dropped, cut to 40 characters. */
+function baseName(path: string): string {
+  const name = path.split(/[\\/]/).pop() ?? "";
+  return name.toLowerCase().replace(/\.(exe|cmd|bat|com)$/, "").slice(0, 40);
+}
+
+function gitLabel(rest: string[]): string {
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!;
+    if (GIT_VALUE_FLAGS.has(a)) { i++; continue; }
+    if (a.startsWith("-")) continue;
+    return /^[a-z][a-z0-9-]*$/.test(a) ? `git ${a}` : "git";
+  }
+  return "git";
+}
+
+function runnerLabel(program: string, rest: string[]): string {
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!;
+    if (EVAL_FLAGS.has(a)) return `${program} ${a}`;
+    if (RUNNER_VALUE_FLAGS.has(a)) { i++; continue; }
+    if (a.startsWith("-")) continue;
+    if (!PLAIN_WORD.test(a)) return program;
+    if (SCRIPT_FILE.test(a)) return `${program} ${baseName(a)}`;
+    if (RUNNER_SUBCOMMANDS.has(a)) return `${program} ${a}`;
+    // `npx <package>`: the package's own name, its scope and version dropped.
+    const pkg = a.match(/^(?:@[\w.-]+\/)?([\w.-]+)(?:@[\w.^~-]+)?$/);
+    if ((program === "npx" || program === "bunx") && pkg) return `${program} ${pkg[1]!.toLowerCase().slice(0, 40)}`;
+    return program;
+  }
+  return program;
+}
+
+function shellLabel(program: string, rest: string[]): string {
+  const at = rest.findIndex((a) => SHELL_COMMAND_FLAGS.has(a.toLowerCase()));
+  const line = at === -1 ? undefined : rest[at + 1];
+  if (line === undefined) return program;
+  const first = line.trim().split(/\s+/)[0] ?? "";
+  if (!first || !PLAIN_WORD.test(first)) return program;
+  return `${program} ${baseName(first)}`;
+}
+
+/** A short, argument-free name for a command line. Exported for tests. */
+export function spawnLabel(argv: readonly unknown[]): string {
+  const parts = argv.filter((a): a is string => typeof a === "string");
+  const [head, ...rest] = parts;
+  if (head === undefined) return "unknown";
+  const program = baseName(head.replace(/^["']|["']$/g, "")).replace(/[^a-z0-9._+-]/g, "");
+  if (!program) return "unknown";
+  if (program === "git") return gitLabel(rest);
+  if (RUNNERS.has(program)) return runnerLabel(program, rest);
+  if (SHELLS.has(program)) return shellLabel(program, rest);
+  return program;
+}
+
+/** `Bun.spawn(cmd[], opts)` or `Bun.spawn({ cmd, ... })`. */
+function argvOf(args: unknown[]): readonly unknown[] {
+  const first = args[0];
+  if (Array.isArray(first)) return first;
+  if (first && typeof first === "object" && Array.isArray((first as { cmd?: unknown }).cmd)) {
+    return (first as { cmd: unknown[] }).cmd;
+  }
+  return [];
+}
+
+export class SpawnTracker {
+  /** Keyed by the child object, not its pid: a pid can be reused before the old child's `exited` settles. */
+  private readonly live = new Map<object, LiveChild>();
+  private interval = new Map<string, number>();
+  private readonly totals = new Map<string, number>();
+  private total = 0;
+  private installed = false;
+  /** Set by the memory watchdog to log long-lived children coming and going. */
+  onLifecycle?: (e: ChildLifecycleEvent) => void;
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  /** Record one spawn. Exported for tests; `install()` calls it for real spawns. */
+  record(label: string, child?: { pid?: number; exited?: Promise<unknown> }, session?: string): void {
+    this.total++;
+    this.interval.set(label, (this.interval.get(label) ?? 0) + 1);
+    this.totals.set(label, (this.totals.get(label) ?? 0) + 1);
+    const pid = child?.pid;
+    if (!child || typeof pid !== "number" || !child.exited) return;
+    const entry: LiveChild = { pid, label, startedAt: this.now(), session };
+    this.live.set(child, entry);
+    const logged = LIFECYCLE_LABEL.test(label);
+    if (logged) this.emit({ event: "start", pid, label, session });
+    const done = () => {
+      this.live.delete(child);
+      if (!logged) return;
+      this.emit({
+        event: "exit", pid, label, session,
+        ageMin: Math.round((this.now() - entry.startedAt) / 60_000),
+        lastPrivateMB: entry.lastPrivateMB,
+      });
+    };
+    child.exited.then(done, done);
+  }
+
+  private emit(e: ChildLifecycleEvent): void {
+    try { this.onLifecycle?.(e); } catch { /* a log line must never break a spawn */ }
+  }
+
+  /** What the tracker knows about a live direct child, by pid. */
+  describe(pid: number): LiveChild | undefined {
+    for (const c of this.live.values()) if (c.pid === pid) return c;
+    return undefined;
+  }
+
+  /** Wrap the two globals. Safe to call twice. */
+  install(): void {
+    if (this.installed) return;
+    this.installed = true;
+    const bun = Bun as unknown as Record<"spawn" | "spawnSync", (...a: unknown[]) => unknown>;
+    const spawn = bun.spawn;
+    const spawnSync = bun.spawnSync;
+    bun.spawn = (...args: unknown[]) => {
+      const child = spawn.apply(Bun, args) as { pid?: number; exited?: Promise<unknown> };
+      try {
+        const argv = argvOf(args);
+        this.record(spawnLabel(argv), child, sessionOf(argv));
+      } catch { /* counting must never break a spawn */ }
+      return child;
+    };
+    bun.spawnSync = (...args: unknown[]) => {
+      try { this.record(spawnLabel(argvOf(args))); } catch { /* as above */ }
+      return spawnSync.apply(Bun, args);
+    };
+  }
+
+  /** Counts since the last call, plus what is alive now. Resets the interval counts. */
+  snapshot(): SpawnSnapshot {
+    const live: Record<string, number> = {};
+    for (const c of this.live.values()) live[c.label] = (live[c.label] ?? 0) + 1;
+    const spawned = Object.fromEntries(this.interval);
+    this.interval = new Map();
+    return { spawned, live, liveTotal: this.live.size, total: this.total };
+  }
+
+  /** The longest-running children, for a threshold alert. */
+  oldestLive(limit: number): Array<{ pid: number; label: string; ageMin: number }> {
+    const t = this.now();
+    return [...this.live.values()]
+      .sort((a, b) => a.startedAt - b.startedAt)
+      .slice(0, limit)
+      .map((c) => ({ pid: c.pid, label: c.label, ageMin: Math.round((t - c.startedAt) / 60_000) }));
+  }
+
+  /** Spawns by label since the tracker started, most first. */
+  topTotals(limit: number): Record<string, number> {
+    return Object.fromEntries([...this.totals.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit));
+  }
+}
+
+export const spawnTracker = new SpawnTracker();

package/src/services/memory-diagnostics.ts

@@ -1,19 +1,37 @@
-import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { appendFileSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { heapStats } from "bun:jsc";
 import { getPpmDir } from "./ppm-dir.ts";
+import { readNativeMemory } from "./memory-diagnostics-native.ts";
+import { spawnTracker } from "./memory-diagnostics-spawns.ts";
+import { diffRequestCounts, requestTracker } from "./memory-diagnostics-requests.ts";
+import { startMemoryWatchdog, summarizeDescendants } from "./memory-watchdog.ts";
 
 /**
- * Opt-in memory monitor for chasing server growth (`PPM_MEM_DIAG=1`).
+ * Memory monitoring for each long-lived PPM process (server, supervisor, edge forwarder).
  *
- * Every interval it appends one JSON line to `<ppm dir>/mem-diag.log`: RSS, the JS heap,
- * the object types that grew most since the previous sample, and any gauges registered by
- * long-lived state (session maps, buffered events). Comparing RSS against `heapSize` is the
- * first fork in the investigation — RSS climbing with a flat heap is native memory (child
- * process pipes, Bun internals), which a heap snapshot cannot show.
+ * Always on: `memory-watchdog.ts`, a summary line in `ppm.log` every 30 minutes plus a WARN
+ * at each private-bytes threshold. Opt-in (`PPM_MEM_DIAG=1`): the detailed monitor below.
  *
- * A V8-format heap snapshot is written the first time the heap crosses each threshold, so
- * two snapshots from the same run can be diffed in Chrome DevTools (Memory → Comparison).
+ * Every interval it appends one JSON line to `<ppm dir>/mem-diag.log` (the supervisor
+ * writes `mem-diag-supervisor.log`): RSS, the JS heap, **private bytes** (the commit charge
+ * that actually runs a machine out of memory — RSS alone hid a 32 GB leak), kernel handles,
+ * the child processes started since the previous line and those still alive, the memory of
+ * every process below this one (by program, and by direct child with the chat session it
+ * serves), the HTTP routes served since the previous line, the object
+ * types that grew most, a few absolute counts of objects that own native resources, and
+ * any gauges registered by long-lived state (session maps, buffered events).
+ *
+ * How to read it: `bun scripts/mem-diag-report.ts` correlates private-byte growth with
+ * spawns and gauges. By hand, the first fork is still private vs heap — private climbing
+ * with a flat heap is native memory (child process pipes, allocator segments), which a
+ * heap snapshot cannot show; then look at what `spawned` and `gauges` did in the lines
+ * where `privateDeltaMB` jumps.
+ *
+ * Two kinds of one-off lines: a V8 heap snapshot the first time the heap crosses each
+ * threshold (diffable in Chrome DevTools → Memory → Comparison), and an `alert` line the
+ * first time private bytes cross each threshold, carrying the oldest live children and the
+ * all-time spawn totals — the state a later reader can no longer reconstruct.
  */
 
 const gauges = new Map<string, () => number>();
@@ -23,23 +41,59 @@ export function registerMemoryGauge(name: string, read: () => number): void {
   gauges.set(name, read);
 }
 
+function readGauges(): Record<string, number | string> {
+  const values: Record<string, number | string> = {};
+  for (const [name, read] of gauges) {
+    try { values[name] = read(); } catch (e) { values[name] = `err: ${(e as Error).message}`; }
+  }
+  return values;
+}
+
 const MB = 1024 * 1024;
 const SNAPSHOT_THRESHOLDS_MB = [1024, 2048, 4096, 8192];
+const PRIVATE_ALERT_THRESHOLDS_MB = [2048, 4096, 8192, 16384, 24576, 32768];
+/** Object types that each hold something outside the JS heap. Absolute counts, every line. */
+const NATIVE_OWNER_TYPES = ["Subprocess", "FSWatcher", "SQLStatement", "ArrayBuffer", "ReadableStream", "WebSocket", "ServerWebSocket", "Timeout"];
+/** ~1 KB a line at 30 s is ~3 MB a day; one rotated copy keeps about two weeks. */
+const MAX_LOG_BYTES = 50 * MB;
+
+export interface MemoryDiagnosticsOptions {
+  /** Which process this is; anything but `server` gets its own log file. */
+  role?: "server" | "supervisor" | "edge";
+}
+
+let started = false;
 
-export function startMemoryDiagnostics(): void {
+export function startMemoryDiagnostics(opts: MemoryDiagnosticsOptions = {}): void {
+  if (started) return;
+  started = true;
+  const role = opts.role ?? "server";
+  spawnTracker.install();
+  startMemoryWatchdog(role, readGauges);
   if (process.env.PPM_MEM_DIAG !== "1") return;
   const intervalMs = Math.max(5_000, Number(process.env.PPM_MEM_DIAG_INTERVAL_MS) || 30_000);
   const dir = getPpmDir();
-  const logPath = join(dir, "mem-diag.log");
+  const logPath = join(dir, role === "server" ? "mem-diag.log" : `mem-diag-${role}.log`);
   const snapDir = join(dir, "heap-snapshots");
   const taken = new Set<number>();
+  const alerted = new Set<number>();
   let lastCounts: Record<string, number> = {};
+  let lastPrivateMB: number | undefined;
   const startedAt = Date.now();
+  let lastRequests = requestTracker.read();
 
-  const sample = () => {
+  const write = (obj: unknown) => {
+    try {
+      if (statSync(logPath).size > MAX_LOG_BYTES) renameSync(logPath, `${logPath}.1`);
+    } catch { /* no file yet */ }
+    appendFileSync(logPath, JSON.stringify(obj) + "\n");
+  };
+
+  const sample = async () => {
     try {
       const mem = process.memoryUsage();
       const stats = heapStats();
+      const native = await readNativeMemory();
       const counts = stats.objectTypeCounts as Record<string, number>;
       const grew = Object.entries(counts)
         .map(([type, n]) => [type, n - (lastCounts[type] ?? 0)] as const)
@@ -48,32 +102,76 @@ export function startMemoryDiagnostics(): void {
         .slice(0, 12);
       lastCounts = counts;
 
-      const gaugeValues: Record<string, number | string> = {};
-      for (const [name, read] of gauges) {
-        try { gaugeValues[name] = read(); } catch (e) { gaugeValues[name] = `err: ${(e as Error).message}`; }
-      }
+      const nativeOwners: Record<string, number> = {};
+      for (const type of NATIVE_OWNER_TYPES) if (counts[type] !== undefined) nativeOwners[type] = counts[type];
 
-      const line = {
+      const spawns = spawnTracker.snapshot();
+      const gaugeValues = readGauges();
+      const children = await summarizeDescendants(process.pid, 10);
+      const requestsNow = requestTracker.read();
+      const requests = diffRequestCounts(lastRequests, requestsNow, 10);
+      lastRequests = requestsNow;
+      const privateDeltaMB = native.privateMB !== undefined && lastPrivateMB !== undefined
+        ? native.privateMB - lastPrivateMB
+        : undefined;
+      if (native.privateMB !== undefined) lastPrivateMB = native.privateMB;
+
+      write({
         t: new Date().toISOString(),
+        role,
+        pid: process.pid,
         upMin: Math.round((Date.now() - startedAt) / 60_000),
         rssMB: Math.round(mem.rss / MB),
+        ...native,
+        privateDeltaMB,
         heapMB: Math.round(stats.heapSize / MB),
+        heapCapacityMB: Math.round(stats.heapCapacity / MB),
+        extraMB: Math.round(stats.extraMemorySize / MB),
         externalMB: Math.round(mem.external / MB),
         arrayBuffersMB: Math.round(mem.arrayBuffers / MB),
         objects: stats.objectCount,
+        protectedObjects: stats.protectedObjectCount,
+        spawned: spawns.spawned,
+        liveChildren: spawns.liveTotal,
+        liveByCommand: spawns.live,
+        spawnTotal: spawns.total,
+        children,
+        requests,
+        nativeOwners,
         grew: Object.fromEntries(grew),
         gauges: gaugeValues,
-      };
-      appendFileSync(logPath, JSON.stringify(line) + "\n");
+      });
+
+      if (native.privateMB !== undefined) {
+        for (const threshold of PRIVATE_ALERT_THRESHOLDS_MB) {
+          if (native.privateMB < threshold || alerted.has(threshold)) continue;
+          alerted.add(threshold);
+          write({
+            t: new Date().toISOString(),
+            role,
+            pid: process.pid,
+            alert: "private-bytes",
+            thresholdMB: threshold,
+            privateMB: native.privateMB,
+            rssMB: Math.round(mem.rss / MB),
+            heapMB: Math.round(stats.heapSize / MB),
+            handles: native.handles,
+            spawnTotals: spawnTracker.topTotals(40),
+            oldestLiveChildren: spawnTracker.oldestLive(40),
+            children,
+            gauges: gaugeValues,
+          });
+        }
+      }
 
       const heapMB = stats.heapSize / MB;
       for (const threshold of SNAPSHOT_THRESHOLDS_MB) {
         if (heapMB < threshold || taken.has(threshold)) continue;
         taken.add(threshold);
         mkdirSync(snapDir, { recursive: true });
-        const file = join(snapDir, `heap-${threshold}MB-${Date.now()}.heapsnapshot`);
+        const file = join(snapDir, `heap-${role}-${threshold}MB-${Date.now()}.heapsnapshot`);
         writeFileSync(file, Bun.generateHeapSnapshot("v8"));
-        appendFileSync(logPath, JSON.stringify({ t: new Date().toISOString(), snapshot: file }) + "\n");
+        write({ t: new Date().toISOString(), role, snapshot: file });
       }
     } catch (e) {
       console.warn(`[mem-diag] sample failed: ${(e as Error).message}`);
@@ -81,6 +179,6 @@ export function startMemoryDiagnostics(): void {
   };
 
   console.log(`[mem-diag] sampling every ${intervalMs}ms → ${logPath}`);
-  sample();
-  setInterval(sample, intervalMs).unref?.();
+  void sample();
+  setInterval(() => { void sample(); }, intervalMs).unref?.();
 }