@hienlh/ppm 0.23.21 → 0.23.22

package/src/server/middleware/cors-headers.ts

@@ -0,0 +1,44 @@
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * The app-wide CORS headers, written onto the handler's own response AFTER it is made.
+ *
+ * Hono's `cors()` sets its headers on `c.res` before `next()`, which makes Hono build a
+ * placeholder response; when the handler then returns its own, the `c.res` setter rebuilds it
+ * as `new Response(res.body, res)` to merge the two. Reading `.body` turns a `Bun.file(...)`
+ * body into Bun's file stream — the one that keeps about the file's size in native memory per
+ * response and never returns it (see `services/file-chunks.ts`). Measured on Bun 1.3.10
+ * (Windows), a 23 MB file: 2.9 MB per response bare, 30.2 MB behind `cors()`, and the
+ * response lost its `Content-Length` (sent chunked). Every static asset, chat image and
+ * download went through that.
+ *
+ * Same answer as `cors()` with its defaults (`origin: "*"`), with one difference: a route that
+ * sets `Access-Control-Allow-Origin` itself keeps it (`cors()` overwrote it, which is why the
+ * design preview had to re-assert `null`).
+ */
+const ALLOW_METHODS = "GET,HEAD,PUT,POST,DELETE,PATCH";
+
+export const corsHeaders: MiddlewareHandler = async (c, next) => {
+  if (c.req.method === "OPTIONS") {
+    // A preflight never reaches a handler, so answering it here rebuilds nothing.
+    const headers = new Headers({ "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": ALLOW_METHODS });
+    const requested = c.req.header("Access-Control-Request-Headers");
+    if (requested) {
+      headers.set("Access-Control-Allow-Headers", requested.split(/\s*,\s*/).join(","));
+      headers.append("Vary", "Access-Control-Request-Headers");
+    }
+    return new Response(null, { status: 204, statusText: "No Content", headers });
+  }
+
+  await next();
+  if (c.res.headers.has("Access-Control-Allow-Origin")) return;
+  try {
+    c.res.headers.set("Access-Control-Allow-Origin", "*");
+  } catch {
+    // A response whose headers are immutable (one passed through from `fetch`) is rebuilt;
+    // its body is a stream already, so there is no file to turn into one.
+    const res = new Response(c.res.body, c.res);
+    res.headers.set("Access-Control-Allow-Origin", "*");
+    c.res = res;
+  }
+};

package/src/server/routes/chat.ts

@@ -1277,7 +1277,10 @@ chatRoutes.get("/uploads/:filename", async (c) => {
     if (c.req.header("if-none-match") === etag) {
       return new Response(null, { status: 304, headers: { ETag: etag } });
     }
-    return new Response(file.stream(), {
+    // The file itself, not `file.stream()`: that stream keeps about the file's size in native
+    // memory per response and never returns it (see `file-chunks.ts`), and chat images are
+    // served every time a tab opens without them cached.
+    return new Response(file, {
       headers: {
         "Content-Type": file.type || "application/octet-stream",
         "Cache-Control": "public, max-age=31536000, immutable",

package/src/server/routes/database-impexp.ts

@@ -310,7 +310,7 @@ impExpJobRoutes.post("/jobs/:id/download", async (c) => {
   const ticket = issueExportTicket({
     fileName: file.name,
     contentType: file.format === "zip" ? "application/zip" : CONTENT_TYPES[file.format],
-    open: () => Bun.file(file.path).stream(),
+    open: () => Bun.file(file.path),
     abandon: () => {},
   });
   return c.json(ok<GridExportTicket>({ ticket, fileName: file.name }));

package/src/server/routes/design-preview.ts

@@ -51,8 +51,8 @@ export function createDesignPreviewRoutes(now: () => number = Date.now) {
   const api = new Hono();
   const content = new Hono();
 
-  // The app's global `cors()` answers `*`, and Hono copies headers set before a handler over
-  // the handler's own response, so the value set below would be lost. Re-assert it after.
+  // Every response here must say `null`, error pages included; asserted after the handler so
+  // it holds whatever an inner layer set. The app's CORS layer leaves an existing value alone.
   content.use("*", async (c, next) => {
     await next();
     c.res.headers.set("Access-Control-Allow-Origin", "null");

package/src/server/ws/chat.ts

@@ -1196,6 +1196,9 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
         const stopped = turnStop ? describeTurnStop(turnStop) : null;
 
         const finalText = entry.finalText;
+        // The consumer outlives the turn (Claude pushes a follow-up into the same stream), so
+        // the next turn's answer must not start with this one's.
+        entry.finalText = undefined;
         import("../../services/notification.service.ts").then(({ notificationService }) => {
           const project = entry.projectName || "Project";
           const session = chatService.getSession(sessionId);

package/src/services/compact-segment.ts

@@ -19,6 +19,7 @@
 import { statSync } from "node:fs";
 import type { ChatMessage } from "../types/chat.ts";
 import { parseJsonlTranscript } from "./jsonl-transcript-parser.ts";
+import { readFileChunks } from "./file-chunks.ts";
 
 /**
  * How many bytes one expand may parse.
@@ -90,26 +91,20 @@ export async function compactSegmentWindow(filePath: string, beforeUuid?: string
   // instead would copy a long record once per chunk it spans.
   const pending: Uint8Array[] = [];
   let at = 0; // file offset of the first pending byte
-  const reader = Bun.file(filePath).stream().getReader();
-  try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      const lastNewline = value.lastIndexOf(NEWLINE);
-      if (lastNewline === -1) {
-        pending.push(value);
-        continue;
-      }
-      const lines = Buffer.concat([...pending, value.subarray(0, lastNewline + 1)]);
-      const stop = scan(lines, at);
-      if (stop !== undefined) return window(stop);
-      at += lines.length;
-      pending.length = 0;
-      pending.push(value.subarray(lastNewline + 1));
+  // Not `Bun.file().stream()`, which keeps about the file's size in native memory per read
+  // (see `file-chunks.ts`). Returning mid-loop closes the file.
+  for await (const value of readFileChunks(filePath)) {
+    const lastNewline = value.lastIndexOf(NEWLINE);
+    if (lastNewline === -1) {
+      pending.push(value);
+      continue;
     }
-  } finally {
-    // Not only `releaseLock`: a stream let go of before its end keeps the file open.
-    await reader.cancel().catch(() => {});
+    const lines = Buffer.concat([...pending, value.subarray(0, lastNewline + 1)]);
+    const stop = scan(lines, at);
+    if (stop !== undefined) return window(stop);
+    at += lines.length;
+    pending.length = 0;
+    pending.push(value.subarray(lastNewline + 1));
   }
   // A last line with no newline yet is still a record the full parse would read.
   const stop = scan(Buffer.concat(pending), at);

package/src/services/database/grid-export-tickets.ts

@@ -15,8 +15,12 @@ import { GRID_EXPORT_TICKET_TTL_MS } from "../../shared/db-grid-export.ts";
 export interface ExportDownload {
   fileName: string;
   contentType: string;
-  /** The file, read from the database as it is sent. */
-  open(): ReadableStream<Uint8Array>;
+  /**
+   * The file, read from the database as it is sent — or, for a file already on disk, the file
+   * itself: a `Bun.file` body is sent by Bun directly, where `Bun.file().stream()` keeps about the
+   * file's size in native memory per download (see `file-chunks.ts`).
+   */
+  open(): ReadableStream<Uint8Array> | Blob;
   /** Lets go of the rows and the connection, when the download never starts. */
   abandon(): void;
 }

package/src/services/database/impexp/readers/file-text.ts

@@ -3,6 +3,7 @@
  * order mark, or UTF-16 with one — what PPM's "CSV for Excel" writes. Bytes that are not text in
  * that encoding fail the read: turned into "�" they would be imported as a different value.
  */
+import { readFileChunks } from "../../../file-chunks.ts";
 
 /** The encoding the first bytes name, and how many of them the mark takes. */
 function encodingOf(head: Uint8Array): { encoding: "utf-8" | "utf-16le" | "utf-16be"; skip: number } {
@@ -30,7 +31,9 @@ function notText(encoding: string): FileTextError {
 
 /** The text of the file at `path`, in pieces as it is read. Stop ends it between two pieces. */
 export async function* fileText(path: string, signal?: AbortSignal): AsyncGenerator<string> {
-  const reader = Bun.file(path).stream().getReader();
+  // Not `Bun.file().stream()`, which keeps about the file's size in native memory per read
+  // (see `file-chunks.ts`) — an import file can be hundreds of MB.
+  const chunks = readFileChunks(path);
   let decoder: TextDecoder | null = null;
   let encoding = "utf-8";
   let head: Uint8Array = new Uint8Array(0);
@@ -55,7 +58,7 @@ export async function* fileText(path: string, signal?: AbortSignal): AsyncGenera
         sliceStart = performance.now();
       }
       signal?.throwIfAborted();
-      const { done, value } = await reader.read();
+      const { done, value } = await chunks.next();
       if (done) break;
       let bytes: Uint8Array = value;
       if (!decoder) {
@@ -75,6 +78,6 @@ export async function* fileText(path: string, signal?: AbortSignal): AsyncGenera
     if (rest) yield rest;
   } finally {
     // Read to its end or not, the file is closed.
-    await reader.cancel().catch(() => {});
+    await chunks.return(undefined).catch(() => {});
   }
 }

package/src/services/edge-forwarder.ts

@@ -21,6 +21,7 @@
 import net from "node:net";
 import { resolveTargetPort, _resetTargetCache } from "./edge-target-resolver.ts";
 import { createLogger, installFileLogSink } from "./logger.ts";
+import { registerMemoryGauge, startMemoryDiagnostics } from "./memory-diagnostics.ts";
 
 const log = createLogger("edge");
 
@@ -42,6 +43,12 @@ const CONNECT_WINDOW_MS = 5000;
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
+/** Client connections open right now, and ever: the memory watchdog's view of the edge's load. */
+let openConnections = 0;
+let totalConnections = 0;
+registerMemoryGauge("edge.openConnections", () => openConnections);
+registerMemoryGauge("edge.totalConnections", () => totalConnections);
+
 /** At most one warning a minute about connections dropped for want of a server. */
 const DROP_WARN_INTERVAL_MS = 60_000;
 let droppedSinceWarning = 0;
@@ -201,6 +208,9 @@ export function startEdgeForwarder(
     // allowHalfOpen keeps the other direction alive when one side sends FIN —
     // long-lived chat WS and SSE streams depend on it.
     const server = net.createServer({ allowHalfOpen: true }, (client) => {
+      openConnections++;
+      totalConnections++;
+      client.once("close", () => { openConnections--; });
       void handleConnection(client, connectWindowMs);
     });
     server.once("error", reject);
@@ -218,6 +228,8 @@ if (process.argv.includes("__edge__")) {
   // Lines go to ppm.log with a timestamp and level like every other process's. The
   // supervisor hands the log over as stderr, so the stderr echo is skipped (see logger.ts).
   installFileLogSink({ echo: "stderr" });
+  // Reads memory through the OS only: it spawns nothing, so the invariant above holds.
+  startMemoryDiagnostics({ role: "edge" });
   const idx = process.argv.indexOf("__edge__");
   const publicPort = parseInt(process.argv[idx + 1] ?? "", 10);
   const host = process.argv[idx + 2] ?? "0.0.0.0";

package/src/services/file-chunks.ts

@@ -0,0 +1,39 @@
+import { open } from "node:fs/promises";
+
+/**
+ * A file's bytes, a piece at a time, through `node:fs/promises` — never `Bun.file().stream()`.
+ *
+ * On Bun 1.3.10 (Windows), every full read through `Bun.file(path).stream()` keeps roughly the
+ * file's size in native memory that is never handed back: a 30 MB transcript read 40 times took
+ * a process from 377 MB to 1,949 MB private, 38 MB a read, with the JS heap back at 18 MB. A
+ * chat tab opening reads the whole transcript this way (`readCompactions`), so a server whose
+ * tabs reconnected all day reached 25 GB committed and the machine ran out of memory. The same
+ * 40 reads through a `FileHandle` stayed flat (0.1 MB a read); so did `createReadStream` and
+ * `readSync`. Measured as private bytes (commit charge), which RSS and the heap both hide.
+ *
+ * Each chunk is a fresh buffer, so a caller may keep it after asking for the next one. Breaking
+ * out of the loop closes the file (the generator's `finally`), so an early stop leaks no handle.
+ *
+ * `fromByte` is inclusive, `toByte` exclusive; both are absolute offsets.
+ */
+export async function* readFileChunks(
+  filePath: string,
+  opts: { fromByte?: number; toByte?: number; chunkBytes?: number } = {},
+): AsyncGenerator<Uint8Array> {
+  const chunkBytes = opts.chunkBytes ?? 512 * 1024;
+  let position = Math.max(0, opts.fromByte ?? 0);
+  const end = opts.toByte ?? Infinity;
+  const handle = await open(filePath, "r");
+  try {
+    while (position < end) {
+      const want = Math.min(chunkBytes, end - position);
+      const buf = new Uint8Array(want);
+      const { bytesRead } = await handle.read(buf, 0, want, position);
+      if (bytesRead === 0) break;
+      position += bytesRead;
+      yield bytesRead === want ? buf : buf.subarray(0, bytesRead);
+    }
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}

package/src/services/file-lines.ts

@@ -15,6 +15,7 @@
  * Neither cost was bounded: both grow with the file, and both were paid on the
  * one thread that also serves every other request.
  */
+import { readFileChunks } from "./file-chunks.ts";
 
 /** How much of the end of a file is read to find the last few lines. */
 export const DEFAULT_TAIL_BYTES = 64 * 1024;
@@ -89,24 +90,16 @@ export async function countLines(filePath: string): Promise<number> {
   let count = 0;
   let lastByte = -1;
   let sinceYield = 0;
-  // `getReader()` rather than `for await`: Bun's ReadableStream is async
-  // iterable at runtime, but the DOM typings it is declared against do not say
-  // so, and a cast to paper over that would outlive the reason for it.
-  const reader = Bun.file(filePath).stream().getReader();
-  try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done || !value) break;
-      for (let i = 0; i < value.length; i++) if (value[i] === 0x0a) count++;
-      if (value.length > 0) lastByte = value[value.length - 1]!;
-      sinceYield += value.length;
-      if (sinceYield >= YIELD_EVERY_BYTES) {
-        sinceYield = 0;
-        await new Promise<void>((r) => setTimeout(r, 0));
-      }
+  // Not `Bun.file().stream()`, which keeps about the file's size in native
+  // memory per read and never returns it (see `file-chunks.ts`).
+  for await (const value of readFileChunks(filePath)) {
+    for (let i = 0; i < value.length; i++) if (value[i] === 0x0a) count++;
+    if (value.length > 0) lastByte = value[value.length - 1]!;
+    sinceYield += value.length;
+    if (sinceYield >= YIELD_EVERY_BYTES) {
+      sinceYield = 0;
+      await new Promise<void>((r) => setTimeout(r, 0));
     }
-  } finally {
-    reader.releaseLock();
   }
   if (lastByte === -1) return 0;              // empty file
   if (lastByte !== 0x0a) count++;             // last line carries no newline

package/src/services/lsp/lsp-manager.ts

@@ -20,6 +20,7 @@ import { resolveBunPath } from "../autostart-generator.ts";
 import { createLogger } from "../logger.ts";
 import { canInstall, lspInstallDir, rustupServerPath } from "./lsp-install.ts";
 import { LspSession, type LspSessionState } from "./lsp-session.ts";
+import { registerMemoryGauge } from "../memory-diagnostics.ts";
 import {
   LANGUAGE_SERVERS,
   ancestorDirs,
@@ -595,3 +596,5 @@ export class LspManager {
 }
 
 export const lspManager = new LspManager();
+
+registerMemoryGauge("lsp.servers", () => lspManager["entries"].size);

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

@@ -0,0 +1,110 @@
+import { readdirSync, readFileSync } from "node:fs";
+
+/**
+ * What the OS says this process holds, beyond what `process.memoryUsage()` reports.
+ *
+ * `rss` is only what is resident right now. A leak of *committed* memory — an allocator
+ * segment reserved and never handed back, a pipe buffer per child — can sit at 30 GB of
+ * private bytes while RSS reads 1–2 GB, because Windows trims the working set and pages
+ * the rest out. That is exactly how the server's leak looked on 20/10/2026: mem-diag said
+ * 1 GB, Windows' low-memory detector named the same pid at 32 GB, and every new child
+ * process died of memory exhaustion. Private bytes are the number that runs the machine
+ * out of commit, so that is the one recorded here.
+ *
+ * Every field is `undefined` when this platform cannot measure it, never `0`.
+ */
+export interface NativeMemory {
+  /** Windows `PrivateUsage` (commit charge); Linux `RssAnon + VmSwap`. */
+  privateMB?: number;
+  /** Windows `PeakWorkingSetSize`; Linux `VmHWM`. */
+  peakRssMB?: number;
+  /** Linux `VmSize` — address space, mostly reservations. */
+  virtualMB?: number;
+  /** Windows kernel handles; Linux open file descriptors. Climbs with leaked pipes and children. */
+  handles?: number;
+  /** Linux only: `Threads` in `/proc/self/status`. */
+  threads?: number;
+}
+
+const MB = 1024 * 1024;
+
+type Win32 = {
+  K32GetProcessMemoryInfo: (process: bigint, counters: number, size: number) => number;
+  GetProcessHandleCount: (process: bigint, count: number) => number;
+};
+
+/** `(HANDLE)-1`, the pseudo handle for the calling process. A bigint, so it crosses FFI unrounded. */
+const CURRENT_PROCESS = -1n;
+/** `sizeof(PROCESS_MEMORY_COUNTERS_EX)` on 64-bit Windows: two DWORDs then nine SIZE_Ts. */
+const COUNTERS_SIZE = 80;
+const OFFSET_PEAK_WORKING_SET = 8;
+const OFFSET_PRIVATE_USAGE = 72;
+
+let win32: Win32 | null | undefined;
+
+async function loadWin32(): Promise<Win32 | null> {
+  if (win32 !== undefined) return win32;
+  try {
+    const { dlopen, FFIType } = await import("bun:ffi");
+    win32 = dlopen("kernel32.dll", {
+      K32GetProcessMemoryInfo: { args: [FFIType.i64, FFIType.ptr, FFIType.u32], returns: FFIType.i32 },
+      GetProcessHandleCount: { args: [FFIType.i64, FFIType.ptr], returns: FFIType.i32 },
+    }).symbols as unknown as Win32;
+  } catch {
+    win32 = null;
+  }
+  return win32;
+}
+
+async function readWindows(): Promise<NativeMemory> {
+  const lib = await loadWin32();
+  if (!lib) return {};
+  const { ptr } = await import("bun:ffi");
+  const out: NativeMemory = {};
+
+  const counters = new Uint8Array(COUNTERS_SIZE);
+  const view = new DataView(counters.buffer);
+  view.setUint32(0, COUNTERS_SIZE, true);
+  if (lib.K32GetProcessMemoryInfo(CURRENT_PROCESS, ptr(counters), COUNTERS_SIZE) !== 0) {
+    out.privateMB = Math.round(Number(view.getBigUint64(OFFSET_PRIVATE_USAGE, true)) / MB);
+    out.peakRssMB = Math.round(Number(view.getBigUint64(OFFSET_PEAK_WORKING_SET, true)) / MB);
+  }
+
+  const handleCount = new Uint32Array(1);
+  if (lib.GetProcessHandleCount(CURRENT_PROCESS, ptr(handleCount)) !== 0) out.handles = handleCount[0];
+  return out;
+}
+
+/** Parse the `kB` lines of `/proc/self/status` that matter here. Exported for tests. */
+export function parseProcStatus(text: string): NativeMemory {
+  const kb = (key: string): number | undefined => {
+    const m = text.match(new RegExp(`^${key}:\\s+(\\d+)\\s+kB`, "m"));
+    return m ? Number(m[1]) : undefined;
+  };
+  const anon = kb("RssAnon");
+  const swap = kb("VmSwap");
+  const hwm = kb("VmHWM");
+  const size = kb("VmSize");
+  const threads = text.match(/^Threads:\s+(\d+)/m);
+  return {
+    privateMB: anon === undefined ? undefined : Math.round((anon + (swap ?? 0)) / 1024),
+    peakRssMB: hwm === undefined ? undefined : Math.round(hwm / 1024),
+    virtualMB: size === undefined ? undefined : Math.round(size / 1024),
+    threads: threads ? Number(threads[1]) : undefined,
+  };
+}
+
+function readLinux(): NativeMemory {
+  const out = parseProcStatus(readFileSync("/proc/self/status", "utf8"));
+  try { out.handles = readdirSync("/proc/self/fd").length; } catch { /* fd count is optional */ }
+  return out;
+}
+
+/** One reading of this process's native memory. Never throws; an unreadable field is left out. */
+export async function readNativeMemory(platform: NodeJS.Platform = process.platform): Promise<NativeMemory> {
+  try {
+    if (platform === "win32") return await readWindows();
+    if (platform === "linux") return readLinux();
+  } catch { /* fall through: no native reading this tick */ }
+  return {};
+}

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

@@ -0,0 +1,200 @@
+/**
+ * Turns `mem-diag.log` into a short answer to "what was growing, and what went with it".
+ *
+ * Pure: takes the log's text, returns lines to print. `scripts/mem-diag-report.ts` is the
+ * command around it.
+ *
+ * The attribution is deliberately simple. Within one process run, every interval has a
+ * private-byte delta and a count of spawns per command. For each command, a slope through
+ * the origin (`Σ count·delta / Σ count²`) estimates MB per spawn, and the correlation says
+ * whether the two actually move together. It cannot separate two commands that always run
+ * together, and a leak not tied to a spawn shows up as growth no command explains — which is
+ * then the cue to look at the gauges and `nativeOwners` trends printed below it.
+ */
+
+export interface DiagLine {
+  t: string;
+  role?: string;
+  pid?: number;
+  upMin?: number;
+  rssMB?: number;
+  privateMB?: number;
+  privateDeltaMB?: number;
+  heapMB?: number;
+  handles?: number;
+  spawned?: Record<string, number>;
+  liveChildren?: number;
+  children?: { count: number; privateMB: number; byName?: Record<string, { n: number; mb: number }> };
+  requests?: { total: number; top: Record<string, { n: number; mb: number }> };
+  nativeOwners?: Record<string, number>;
+  gauges?: Record<string, number | string>;
+  alert?: string;
+  snapshot?: string;
+}
+
+export interface CommandAttribution {
+  label: string;
+  spawns: number;
+  mbPerSpawn: number;
+  correlation: number;
+}
+
+/** Parse the log, skipping torn or foreign lines. */
+export function parseDiagLog(text: string): DiagLine[] {
+  const out: DiagLine[] = [];
+  for (const raw of text.split("\n")) {
+    if (!raw.trim()) continue;
+    try {
+      const obj = JSON.parse(raw) as DiagLine;
+      if (typeof obj.t === "string") out.push(obj);
+    } catch { /* a line cut by a crash mid-write */ }
+  }
+  return out;
+}
+
+/** Split samples into process runs: a new pid, or uptime going backwards, starts a run. */
+export function splitRuns(lines: DiagLine[]): DiagLine[][] {
+  const runs: DiagLine[][] = [];
+  let current: DiagLine[] = [];
+  for (const l of lines) {
+    if (l.alert || l.snapshot || l.rssMB === undefined) continue;
+    const prev = current[current.length - 1];
+    const restarted = prev && ((l.pid !== undefined && prev.pid !== undefined && l.pid !== prev.pid)
+      || (l.upMin !== undefined && prev.upMin !== undefined && l.upMin < prev.upMin));
+    if (restarted) { runs.push(current); current = []; }
+    current.push(l);
+  }
+  if (current.length) runs.push(current);
+  return runs;
+}
+
+/** MB-per-spawn and correlation per command over one run's intervals. */
+export function attributeGrowth(run: DiagLine[], minSpawns = 5): CommandAttribution[] {
+  const samples = run.filter((l) => typeof l.privateDeltaMB === "number" && l.spawned);
+  const labels = new Set<string>();
+  for (const s of samples) for (const k of Object.keys(s.spawned!)) labels.add(k);
+  const deltas = samples.map((s) => s.privateDeltaMB!);
+  const out: CommandAttribution[] = [];
+  for (const label of labels) {
+    const counts = samples.map((s) => s.spawned![label] ?? 0);
+    const spawns = counts.reduce((a, b) => a + b, 0);
+    if (spawns < minSpawns) continue;
+    let cd = 0, cc = 0;
+    counts.forEach((c, i) => { cd += c * (deltas[i] ?? 0); cc += c * c; });
+    out.push({ label, spawns, mbPerSpawn: cc ? cd / cc : 0, correlation: pearson(counts, deltas) });
+  }
+  return out.sort((a, b) => b.mbPerSpawn * b.spawns - a.mbPerSpawn * a.spawns);
+}
+
+function pearson(x: number[], y: number[]): number {
+  const n = x.length;
+  if (n < 3) return 0;
+  const mx = x.reduce((a, b) => a + b, 0) / n;
+  const my = y.reduce((a, b) => a + b, 0) / n;
+  let sxy = 0, sxx = 0, syy = 0;
+  x.forEach((xi, i) => {
+    const dx = xi - mx, dy = (y[i] ?? 0) - my;
+    sxy += dx * dy; sxx += dx * dx; syy += dy * dy;
+  });
+  return sxx && syy ? sxy / Math.sqrt(sxx * syy) : 0;
+}
+
+/** Numeric series that grew most between a run's first and last sample. */
+function trends(first0: DiagLine, last0: DiagLine, pick: (l: DiagLine) => Record<string, number | string> | undefined): Array<[string, number, number]> {
+  const first = pick(first0) ?? {};
+  const last = pick(last0) ?? {};
+  const rows: Array<[string, number, number]> = [];
+  for (const [k, v] of Object.entries(last)) {
+    const a = Number(first[k] ?? 0), b = Number(v);
+    if (Number.isFinite(a) && Number.isFinite(b) && b !== a) rows.push([k, a, b]);
+  }
+  return rows.sort((p, q) => (q[2] - q[1]) - (p[2] - p[1]));
+}
+
+const fmt = (n: number | undefined, unit = "") => (n === undefined ? "—" : `${Math.round(n).toLocaleString("en-US")}${unit}`);
+
+/** The whole report as printable lines. `lastRuns` limits output to the most recent runs. */
+export function buildReport(text: string, lastRuns = 3): string[] {
+  const lines = parseDiagLog(text);
+  const out: string[] = [];
+  const runs = splitRuns(lines).slice(-lastRuns);
+  if (runs.length === 0) return ["No samples in the log. Is PPM_MEM_DIAG=1 set for the process?"];
+
+  for (const run of runs) {
+    const a = run[0], z = run[run.length - 1];
+    if (!a || !z) continue;
+    const hours = Math.max(1 / 60, (Date.parse(z.t) - Date.parse(a.t)) / 3_600_000);
+    out.push("", `== ${a.role ?? "server"} pid=${a.pid ?? "?"}  ${a.t} → ${z.t}  (${hours.toFixed(1)} h, ${run.length} samples)`);
+    if (a.privateMB === undefined) {
+      out.push("   This run predates private-byte sampling: only RSS/heap are available.");
+    } else {
+      const rate = ((z.privateMB ?? 0) - (a.privateMB ?? 0)) / hours;
+      out.push(`   private ${fmt(a.privateMB)} → ${fmt(z.privateMB)} MB  (${rate >= 0 ? "+" : ""}${fmt(rate)} MB/h)`);
+      // Growth the JS heap accounts for is a heap-snapshot problem, not a native one.
+      const heapGrowth = (z.heapMB ?? 0) - (a.heapMB ?? 0);
+      const privateGrowth = (z.privateMB ?? 0) - (a.privateMB ?? 0);
+      if (privateGrowth > 0) out.push(`   JS heap explains ${fmt(Math.max(0, heapGrowth))} MB of that ${fmt(privateGrowth)} MB; the rest is native`);
+    }
+    out.push(`   rss ${fmt(a.rssMB)} → ${fmt(z.rssMB)} MB   heap ${fmt(a.heapMB)} → ${fmt(z.heapMB)} MB   handles ${fmt(a.handles)} → ${fmt(z.handles)}   live children ${fmt(a.liveChildren)} → ${fmt(z.liveChildren)}`);
+
+    if (a.children || z.children) {
+      const names = Object.entries(z.children?.byName ?? {}).sort((p, q) => q[1].mb - p[1].mb).slice(0, 5)
+        .map(([k, v]) => `${k}×${v.n} ${fmt(v.mb)} MB`).join(", ");
+      out.push(`   children private ${fmt(a.children?.privateMB)} → ${fmt(z.children?.privateMB)} MB (${fmt(z.children?.count)} processes${names ? `: ${names}` : ""})`);
+    }
+
+    const routes = new Map<string, { n: number; mb: number }>();
+    for (const l of run) {
+      for (const [k, v] of Object.entries(l.requests?.top ?? {})) {
+        const r = routes.get(k) ?? { n: 0, mb: 0 };
+        r.n += v.n;
+        r.mb += v.mb;
+        routes.set(k, r);
+      }
+    }
+    if (routes.size) {
+      out.push("   Busiest routes over the run (each sample keeps its top 10):");
+      for (const [k, v] of [...routes].sort((p, q) => q[1].n - p[1].n).slice(0, 8)) {
+        out.push(`     ${k.padEnd(44)} ${String(v.n).padStart(7)} requests  ${v.mb.toFixed(1).padStart(8)} MB sent`);
+      }
+    }
+
+    const attribution = attributeGrowth(run);
+    if (attribution.length) {
+      out.push("   Spawns vs private growth (slope through origin; correlation -1..1):");
+      for (const c of attribution.slice(0, 12)) {
+        out.push(`     ${c.label.padEnd(32)} ${String(c.spawns).padStart(6)} spawns  ${c.mbPerSpawn.toFixed(1).padStart(7)} MB/spawn  r=${c.correlation.toFixed(2)}`);
+      }
+    }
+
+    const jumps = run
+      .filter((l) => (l.privateDeltaMB ?? 0) > 0)
+      .sort((p, q) => (q.privateDeltaMB ?? 0) - (p.privateDeltaMB ?? 0))
+      .slice(0, 8);
+    if (jumps.length) {
+      out.push("   Largest single-interval jumps:");
+      for (const j of jumps) {
+        const spawned = Object.entries(j.spawned ?? {}).sort((p, q) => q[1] - p[1]).slice(0, 5).map(([k, v]) => `${k}×${v}`).join(", ");
+        out.push(`     ${j.t}  +${fmt(j.privateDeltaMB)} MB  spawned: ${spawned || "none"}`);
+      }
+    }
+
+    const gaugeTrends = trends(a, z, (l) => l.gauges).slice(0, 10);
+    if (gaugeTrends.length) {
+      out.push("   Gauges (first → last):");
+      for (const [k, x, y] of gaugeTrends) out.push(`     ${k.padEnd(32)} ${fmt(x)} → ${fmt(y)}`);
+    }
+    const ownerTrends = trends(a, z, (l) => l.nativeOwners).slice(0, 8);
+    if (ownerTrends.length) {
+      out.push("   Objects owning native memory (first → last):");
+      for (const [k, x, y] of ownerTrends) out.push(`     ${k.padEnd(32)} ${fmt(x)} → ${fmt(y)}`);
+    }
+  }
+
+  const alerts = lines.filter((l) => l.alert);
+  if (alerts.length) {
+    out.push("", "Threshold alerts (full detail is in the log line):");
+    for (const al of alerts.slice(-10)) out.push(`   ${al.t}  ${al.role ?? "server"} pid=${al.pid}  ${al.alert}  ${fmt((al as { privateMB?: number }).privateMB)} MB`);
+  }
+  return out;
+}