@hienlh/ppm 0.23.21 → 0.23.23

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;
+}

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();