@hienlh/ppm 0.23.21 → 0.23.23

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?.();
 }

package/src/services/memory-watchdog.ts

@@ -0,0 +1,185 @@
+/**
+ * Always-on memory watchdog: a few lines in `ppm.log`, so that "why is PPM using so much RAM"
+ * has an answer in the log a user already has, without anyone having set `PPM_MEM_DIAG`.
+ *
+ * Every minute it reads this process's private bytes and those of every process below it
+ * (one OS call, ~8 ms on Windows). It writes:
+ * - a summary line every 30 minutes — this process, its children by program, the biggest child
+ *   branches with the chat session each one serves, the busiest HTTP routes since the last
+ *   summary, and the registered gauges (sessions, clients, terminals…). WARN instead of INFO
+ *   when private bytes grew by a gigabyte or more since the previous summary;
+ * - a WARN the first time private bytes (and, for the server, its children's total) cross each
+ *   threshold, with the same detail;
+ * - an INFO when a Claude/Codex subprocess starts or exits, with its pid, its session and what
+ *   it held at its last reading — the pid in the summary is then traceable to a chat.
+ *
+ * What it answered on 26/10/2026, after the fact and by hand: the server at 7 GB while its JS
+ * heap was 186 MB (a native leak), and 17 Claude subprocesses at ~650 MB each (by design, one
+ * per open chat). Both halves are in one summary line now.
+ *
+ * The detailed per-30-second JSON stays behind `PPM_MEM_DIAG=1` (`memory-diagnostics.ts`).
+ */
+import { createLogger } from "./logger.ts";
+import { readNativeMemory } from "./memory-diagnostics-native.ts";
+import { spawnTracker } from "./memory-diagnostics-spawns.ts";
+import { diffRequestCounts, requestTracker } from "./memory-diagnostics-requests.ts";
+import { descendantsOf, readProcessList } from "./process-tree-memory.ts";
+import { heapStats } from "bun:jsc";
+
+const log = createLogger("mem");
+
+const MB = 1024 * 1024;
+const WATCH_INTERVAL_MS = 60_000;
+const SUMMARY_INTERVAL_MS = 30 * 60_000;
+/** Growth between two summaries that turns the summary into a WARN. */
+const FAST_GROWTH_MB = 1024;
+const SELF_ALERT_MB = [2048, 4096, 8192, 16384, 32768];
+const CHILDREN_ALERT_MB = [8192, 16384, 24576, 32768];
+
+export interface ChildBranch {
+  pid: number;
+  name: string;
+  /** The tracker's label for a direct child, when it saw the spawn. */
+  label?: string;
+  session?: string;
+  ageMin?: number;
+  /** The child alone. */
+  ownMB: number;
+  /** The child and everything below it. */
+  treeMB: number;
+}
+
+export interface TreeSummary {
+  count: number;
+  privateMB: number;
+  byName: Record<string, { n: number; mb: number }>;
+  /** Direct children, biggest subtree first. */
+  branches: ChildBranch[];
+}
+
+/** Read the tree below `rootPid` and fold it by program and by direct child. Undefined when unreadable. */
+export async function summarizeDescendants(rootPid: number, limit: number): Promise<TreeSummary | undefined> {
+  const list = await readProcessList(rootPid);
+  if (!list) return undefined;
+  const all = descendantsOf(rootPid, list);
+  const byName: TreeSummary["byName"] = {};
+  const branches = new Map<number, ChildBranch>();
+  let privateMB = 0;
+  for (const d of all) {
+    privateMB += d.privateMB;
+    const n = (byName[d.name] ??= { n: 0, mb: 0 });
+    n.n++;
+    n.mb += d.privateMB;
+    if (d.depth === 1) {
+      const tracked = spawnTracker.describe(d.pid);
+      if (tracked) tracked.lastPrivateMB = d.privateMB;
+      branches.set(d.pid, {
+        pid: d.pid, name: d.name, label: tracked?.label, session: tracked?.session,
+        ageMin: tracked ? Math.round((Date.now() - tracked.startedAt) / 60_000) : undefined,
+        ownMB: d.privateMB, treeMB: 0,
+      });
+    }
+  }
+  for (const d of all) {
+    const b = branches.get(d.branchPid);
+    if (b) b.treeMB += d.privateMB;
+  }
+  return {
+    count: all.length,
+    privateMB,
+    byName,
+    branches: [...branches.values()].sort((a, b) => b.treeMB - a.treeMB).slice(0, limit),
+  };
+}
+
+const plural = (n: number, mb: number) => `${n > 1 ? `×${n} ` : ""}${mb}MB`;
+
+/** The children half of a log line. Exported for tests. */
+export function describeTree(tree: TreeSummary | undefined): string {
+  if (!tree) return "children unreadable";
+  if (tree.count === 0) return "no children";
+  const names = Object.entries(tree.byName)
+    .sort((a, b) => b[1].mb - a[1].mb).slice(0, 6)
+    .map(([name, v]) => `${name} ${plural(v.n, v.mb)}`).join(", ");
+  const biggest = tree.branches.slice(0, 5).map((b) => {
+    const who = b.session ? `session=${b.session.slice(0, 8)}` : b.label ?? b.name;
+    const own = b.treeMB !== b.ownMB ? ` (own ${b.ownMB}MB)` : "";
+    const age = b.ageMin !== undefined ? ` ${b.ageMin}m` : "";
+    return `${b.name} pid=${b.pid} ${who}${age} ${b.treeMB}MB${own}`;
+  }).join("; ");
+  return `children ${tree.count} = ${tree.privateMB}MB [${names}] biggest: ${biggest}`;
+}
+
+function describeRequests(top: Record<string, { n: number; mb: number; streamed: number }>, total: number): string {
+  const rows = Object.entries(top).map(([k, v]) => `${k} ×${v.n}${v.mb ? ` ${v.mb}MB` : ""}${v.streamed ? ` (${v.streamed} streamed)` : ""}`);
+  return `requests ${total}${rows.length ? `: ${rows.join(", ")}` : ""}`;
+}
+
+function describeGauges(gauges: Record<string, number | string>): string {
+  const rows = Object.entries(gauges).map(([k, v]) => `${k}=${v}`);
+  return rows.length ? `gauges ${rows.join(" ")}` : "";
+}
+
+export function startMemoryWatchdog(role: string, readGauges: () => Record<string, number | string>): void {
+  const startedAt = Date.now();
+  const selfAlerted = new Set<number>();
+  const childAlerted = new Set<number>();
+  // The first summary comes a minute after start: the baseline every later line is read against.
+  let lastSummaryAt = Date.now() - SUMMARY_INTERVAL_MS + WATCH_INTERVAL_MS;
+  let lastSummaryPrivateMB: number | undefined;
+  let lastRequests = requestTracker.read();
+
+  spawnTracker.onLifecycle = (e) => {
+    const who = `${e.label} pid=${e.pid}${e.session ? ` session=${e.session}` : ""}`;
+    if (e.event === "start") log.info(`${who} started`);
+    else log.info(`${who} exited after ${e.ageMin}m${e.lastPrivateMB !== undefined ? `, held ${e.lastPrivateMB}MB at its last reading` : ""}`);
+  };
+
+  const tick = async () => {
+    try {
+      const native = await readNativeMemory();
+      const tree = await summarizeDescendants(process.pid, 5);
+      const self = native.privateMB;
+      const crossedSelf = self === undefined ? [] : SELF_ALERT_MB.filter((t) => self >= t && !selfAlerted.has(t));
+      const crossedChildren = role === "server" && tree
+        ? CHILDREN_ALERT_MB.filter((t) => tree.privateMB >= t && !childAlerted.has(t))
+        : [];
+      const summaryDue = Date.now() - lastSummaryAt >= SUMMARY_INTERVAL_MS;
+      if (!crossedSelf.length && !crossedChildren.length && !summaryDue) return;
+
+      const heapMB = Math.round(heapStats().heapSize / MB);
+      const rssMB = Math.round(process.memoryUsage().rss / MB);
+      const upMin = Math.round((Date.now() - startedAt) / 60_000);
+      const head = `${role} pid=${process.pid} up=${upMin}m private=${self ?? "?"}MB heap=${heapMB}MB rss=${rssMB}MB handles=${native.handles ?? "?"}`;
+      const tail = [describeTree(tree), describeGauges(readGauges())].filter(Boolean).join(" | ");
+
+      // One line per crossing, naming the highest threshold passed since the last tick.
+      if (crossedSelf.length) {
+        for (const t of crossedSelf) selfAlerted.add(t);
+        log.warn(`${role} private bytes crossed ${Math.max(...crossedSelf)}MB (heap ${heapMB}MB, so ~${Math.max(0, (self ?? 0) - heapMB)}MB is native) — ${head} | ${tail}`);
+      }
+      if (crossedChildren.length) {
+        for (const t of crossedChildren) childAlerted.add(t);
+        log.warn(`${role} children crossed ${Math.max(...crossedChildren)}MB together — ${head} | ${tail}`);
+      }
+      if (!summaryDue) return;
+
+      const now = requestTracker.read();
+      const requests = diffRequestCounts(lastRequests, now, 6);
+      lastRequests = now;
+      const minutes = Math.round((Date.now() - lastSummaryAt) / 60_000);
+      const growth = self !== undefined && lastSummaryPrivateMB !== undefined ? self - lastSummaryPrivateMB : undefined;
+      lastSummaryAt = Date.now();
+      if (self !== undefined) lastSummaryPrivateMB = self;
+      const growthText = growth === undefined ? "" : ` (${growth >= 0 ? "+" : ""}${growth}MB in ${minutes}m)`;
+      const reqText = requests.total ? ` | ${describeRequests(requests.top, requests.total)}` : "";
+      const line = `summary ${head}${growthText} | ${tail}${reqText}`;
+      if (growth !== undefined && growth >= FAST_GROWTH_MB) log.warn(`${line} — private bytes grew fast`);
+      else log.info(line);
+    } catch (e) {
+      log.debug(`watchdog tick failed: ${(e as Error).message}`);
+    }
+  };
+
+  setInterval(() => { void tick(); }, WATCH_INTERVAL_MS).unref?.();
+}

package/src/services/nested-subagent-spy.ts

@@ -30,6 +30,7 @@ import type { ChatEvent } from "../types/chat.ts";
 import { createAgentTranscriptLineParser } from "./subagent-transcript-merger.ts";
 import { getCachedSubagentGroups } from "./agent-transcript/agent-transcript-index-cache.ts";
 import { createLogger } from "./logger.ts";
+import { registerMemoryGauge } from "./memory-diagnostics.ts";
 
 const log = createLogger("nested-spy");
 
@@ -207,3 +208,5 @@ function stopAllForSession(sessionId: string): void {
 }
 
 export const nestedSubagentSpy = { startSpy, stopSpy, stopAllForSession };
+
+registerMemoryGauge("nestedSubagentSpy.sessions", () => sessions.size);

package/src/services/process-thread-snapshot.ts

@@ -109,7 +109,12 @@ const STATUS_INFO_LENGTH_MISMATCH = 0xc0000004 | 0;
 /** Grows on a length mismatch; a busy machine needs ~1-2 MB. */
 let bufferSize = 2 * 1024 * 1024;
 
-async function readWindows(pid: number): Promise<ThreadSnapshot | null> {
+/**
+ * One `SystemProcessInformation` reading of every process on the machine, or null when it
+ * cannot be taken. `base` is the buffer's address: the image names inside it are pointers
+ * into the same buffer, so `pointer - base` is their offset in `view`.
+ */
+export async function querySystemProcessInformation(): Promise<{ view: DataView; base: bigint } | null> {
   if (ntdll === undefined) {
     try {
       const { dlopen, FFIType } = await import("bun:ffi");
@@ -131,11 +136,16 @@ async function readWindows(pid: number): Promise<ThreadSnapshot | null> {
       continue;
     }
     if (status !== 0) return null;
-    return parseWindowsProcessInformation(new DataView(buf.buffer), pid);
+    return { view: new DataView(buf.buffer), base: BigInt(ptr(buf)) };
   }
   return null;
 }
 
+async function readWindows(pid: number): Promise<ThreadSnapshot | null> {
+  const info = await querySystemProcessInformation();
+  return info ? parseWindowsProcessInformation(info.view, pid) : null;
+}
+
 const LINUX_STATES: Record<string, string> = {
   R: "running", S: "sleeping", D: "disk-wait", T: "stopped", t: "traced", Z: "zombie", X: "dead",
   I: "idle", W: "paging", P: "parked",

package/src/services/process-tree-memory.ts

@@ -0,0 +1,161 @@
+/**
+ * How much memory every process below this one holds, read from the OS.
+ *
+ * The monitor's own numbers cover one process, and on 26/10/2026 that was the smaller half:
+ * the server held 7 GB while its 17 Claude subprocesses held 11 GB between them, and nothing
+ * PPM logged could say so. The spawn tracker only sees direct children, and only the ones
+ * started after it was installed; the OS sees the whole tree, grandchildren included (an MCP
+ * server under a Claude subprocess, a test runner under a shell).
+ *
+ * Windows reads every process with one `NtQuerySystemInformation` call (the same one
+ * `process-thread-snapshot.ts` makes); Linux walks `/proc`. Other platforms answer null.
+ * Nothing here throws.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { querySystemProcessInformation } from "./process-thread-snapshot.ts";
+
+export interface ProcessMemoryEntry {
+  pid: number;
+  ppid: number;
+  /** Image name, lowercased, executable extension dropped. */
+  name: string;
+  privateMB: number;
+  /** When the process started, ms since the epoch on Windows and since boot on Linux: only compared, never shown. */
+  startedAt: number;
+}
+
+const MB = 1024 * 1024;
+
+// SYSTEM_PROCESS_INFORMATION on 64-bit Windows.
+const P_NEXT = 0x00;
+const P_CREATE_TIME = 0x20;
+const P_IMAGE_NAME_LENGTH = 0x38;
+const P_IMAGE_NAME_BUFFER = 0x40;
+const P_PID = 0x50;
+const P_PARENT_PID = 0x58;
+const P_PRIVATE_BYTES = 0xc8;
+const P_SIZE = 0x100;
+/** 100 ns ticks between 1601-01-01 and 1970-01-01. */
+const EPOCH_TICKS = 116_444_736_000_000_000n;
+
+export function processName(raw: string): string {
+  return raw.toLowerCase().replace(/\.(exe|cmd|bat|com)$/, "").slice(0, 40) || "unknown";
+}
+
+/** Every process in a `SystemProcessInformation` buffer. Exported for tests. */
+export function parseWindowsProcessList(view: DataView, base: bigint): ProcessMemoryEntry[] {
+  const out: ProcessMemoryEntry[] = [];
+  let at = 0;
+  for (;;) {
+    if (at + P_SIZE > view.byteLength) break;
+    const pid = Number(view.getBigUint64(at + P_PID, true));
+    let name = pid === 0 ? "idle" : "system";
+    const nameBytes = view.getUint16(at + P_IMAGE_NAME_LENGTH, true);
+    const namePtr = view.getBigUint64(at + P_IMAGE_NAME_BUFFER, true);
+    const offset = Number(namePtr - base);
+    if (nameBytes > 0 && offset >= 0 && offset + nameBytes <= view.byteLength) {
+      name = new TextDecoder("utf-16le").decode(new Uint8Array(view.buffer, view.byteOffset + offset, nameBytes));
+    }
+    const created = view.getBigInt64(at + P_CREATE_TIME, true);
+    out.push({
+      pid,
+      ppid: Number(view.getBigUint64(at + P_PARENT_PID, true)),
+      name: processName(name),
+      privateMB: Math.round(Number(view.getBigUint64(at + P_PRIVATE_BYTES, true)) / MB),
+      startedAt: created > EPOCH_TICKS ? Number((created - EPOCH_TICKS) / 10_000n) : 0,
+    });
+    const next = view.getUint32(at + P_NEXT, true);
+    if (next === 0) break;
+    at += next;
+  }
+  return out;
+}
+
+/** `/proc/<pid>/stat` → ppid, name and start time (field 22, clock ticks since boot). Exported for tests. */
+export function parseLinuxStatLine(text: string): { ppid: number; name: string; startedAt: number } | null {
+  const open = text.indexOf("(");
+  const close = text.lastIndexOf(")");
+  if (open === -1 || close === -1) return null;
+  const f = text.slice(close + 2).trim().split(/\s+/);
+  const ppid = Number(f[4 - 3]);
+  const startedAt = Number(f[22 - 3]);
+  if (!Number.isFinite(ppid)) return null;
+  return { ppid, name: processName(text.slice(open + 1, close)), startedAt: Number.isFinite(startedAt) ? startedAt : 0 };
+}
+
+function linuxPrivateMB(pid: number): number {
+  try {
+    const status = readFileSync(`/proc/${pid}/status`, "utf8");
+    const kb = (key: string) => Number(status.match(new RegExp(`^${key}:\\s+(\\d+)`, "m"))?.[1] ?? 0);
+    return Math.round((kb("RssAnon") + kb("VmSwap")) / 1024);
+  } catch {
+    return 0;
+  }
+}
+
+function readLinuxList(rootPid: number): ProcessMemoryEntry[] {
+  const all: ProcessMemoryEntry[] = [];
+  for (const entry of readdirSync("/proc")) {
+    const pid = Number(entry);
+    if (!Number.isInteger(pid)) continue;
+    try {
+      const stat = parseLinuxStatLine(readFileSync(`/proc/${pid}/stat`, "utf8"));
+      if (stat) all.push({ pid, ...stat, privateMB: 0 });
+    } catch { /* exited while walking */ }
+  }
+  // Memory only for the tree that is reported: one status read per descendant, not per process.
+  const tree = new Set(descendantsOf(rootPid, all).map((d) => d.pid));
+  for (const p of all) if (tree.has(p.pid) || p.pid === rootPid) p.privateMB = linuxPrivateMB(p.pid);
+  return all;
+}
+
+/** Every process the OS lists, or null when this platform cannot be read. */
+export async function readProcessList(rootPid = process.pid, platform: NodeJS.Platform = process.platform): Promise<ProcessMemoryEntry[] | null> {
+  try {
+    if (platform === "win32") {
+      const info = await querySystemProcessInformation();
+      return info ? parseWindowsProcessList(info.view, info.base) : null;
+    }
+    if (platform === "linux") return readLinuxList(rootPid);
+  } catch { /* fall through */ }
+  return null;
+}
+
+export interface Descendant extends ProcessMemoryEntry {
+  depth: number;
+  /** The direct child of the root this process descends from (itself, at depth 1). */
+  branchPid: number;
+}
+
+/**
+ * Every process below `rootPid`. A process counts as a child only if it started after its
+ * parent: Windows reuses pids, so a ppid can name an unrelated process that took a dead
+ * parent's number, and without the check that process's whole tree would be claimed.
+ */
+export function descendantsOf(rootPid: number, list: ProcessMemoryEntry[]): Descendant[] {
+  const byParent = new Map<number, ProcessMemoryEntry[]>();
+  const byPid = new Map<number, ProcessMemoryEntry>();
+  for (const p of list) {
+    byPid.set(p.pid, p);
+    if (p.pid === p.ppid) continue;
+    const siblings = byParent.get(p.ppid);
+    if (siblings) siblings.push(p); else byParent.set(p.ppid, [p]);
+  }
+  const out: Descendant[] = [];
+  const queue: Array<{ p: ProcessMemoryEntry; depth: number; branchPid: number }> = [];
+  const root = byPid.get(rootPid);
+  for (const c of byParent.get(rootPid) ?? []) {
+    if (!root || c.startedAt >= root.startedAt) queue.push({ p: c, depth: 1, branchPid: c.pid });
+  }
+  const seen = new Set<number>([rootPid]);
+  while (queue.length) {
+    const { p, depth, branchPid } = queue.shift()!;
+    if (seen.has(p.pid)) continue;
+    seen.add(p.pid);
+    out.push({ ...p, depth, branchPid });
+    for (const c of byParent.get(p.pid) ?? []) {
+      if (c.startedAt >= p.startedAt) queue.push({ p: c, depth: depth + 1, branchPid });
+    }
+  }
+  return out;
+}

package/src/services/read-lines.ts

@@ -5,6 +5,7 @@
  * compaction scan — and having the second import it from the first would make the
  * two files a cycle.
  */
+import { readFileChunks } from "./file-chunks.ts";
 
 /**
  * Yield a file's lines without holding the file in memory.
@@ -19,47 +20,35 @@
  *
  * `toByte` ends the read there, exclusive. It is meant to be a line start (the
  * record that begins there is not read) or omitted for the end of the file —
- * `compactSegmentWindow` in `compact-segment.ts` is what computes one. It is
- * counted here rather than handed to `slice()` as an end, because in Bun 1.3.11
- * a sliced file's stream that has to stop well short of EOF never finishes:
- * on a 4MB file `slice(0, 259).stream()` hung, `slice(0, 4194303)` did not.
+ * `compactSegmentWindow` in `compact-segment.ts` is what computes one.
+ *
+ * The bytes come from `readFileChunks`, not `Bun.file().stream()`: that stream
+ * keeps about the file's size in native memory per full read and never returns
+ * it (see `file-chunks.ts`), and its sliced form never finishes when it has to
+ * stop well short of EOF (Bun 1.3.11: on a 4MB file `slice(0, 259).stream()`
+ * hung).
  */
 export async function* readLines(filePath: string, fromByte = 0, toByte?: number): AsyncGenerator<string> {
   const decoder = new TextDecoder();
-  // Explicit reader rather than `for await` over the stream: the DOM lib's
-  // ReadableStream is not typed as async-iterable, and the `finally` is what
-  // releases it when a caller breaks early on `beforeUuid`.
   // One byte *before* the offset, so the first line the split produces is
   // always the tail of the record the offset fell inside — the empty string
   // when it fell exactly on a newline. That makes the drop below unconditional
   // instead of a boundary case, and a boundary case here silently costs a whole
   // record rather than a fragment.
-  const file = fromByte > 0 ? Bun.file(filePath).slice(fromByte - 1) : Bun.file(filePath);
-  const reader = file.stream().getReader();
   // A fragment is not always unparseable — the tail of one record is sometimes
   // a complete smaller document — so it has to go by position rather than be
   // left for `JSON.parse` to reject, or it enters as an invented message.
   let dropPartial = fromByte > 0;
-  let remaining = toByte === undefined ? Infinity : toByte - Math.max(0, fromByte - 1);
   let buffered = "";
-  try {
-    while (remaining > 0) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      const chunk = value.byteLength > remaining ? value.subarray(0, remaining) : value;
-      remaining -= chunk.byteLength;
-      buffered += decoder.decode(chunk, { stream: true });
-      const lines = buffered.split("\n");
-      buffered = lines.pop() ?? "";
-      for (const line of lines) {
-        if (dropPartial) { dropPartial = false; continue; }
-        yield line;
-      }
+  // A caller that stops early (`beforeUuid`) ends this loop, which closes the file.
+  for await (const chunk of readFileChunks(filePath, { fromByte: Math.max(0, fromByte - 1), toByte })) {
+    buffered += decoder.decode(chunk, { stream: true });
+    const lines = buffered.split("\n");
+    buffered = lines.pop() ?? "";
+    for (const line of lines) {
+      if (dropPartial) { dropPartial = false; continue; }
+      yield line;
     }
-  } finally {
-    // `cancel`, not only `releaseLock`: a stream let go of before its end keeps
-    // the file open — 2000 early stops left 2000 descriptors behind.
-    await reader.cancel().catch(() => {});
   }
   buffered += decoder.decode();
   if (buffered && !dropPartial) yield buffered;