@vellumai/assistant 0.12.4-dev.202609232215.634e2d2 → 0.12.4-dev.202609232312.d1432a4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.4-dev.202609232215.634e2d2",
+  "version": "0.12.4-dev.202609232312.d1432a4",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/daemon/event-loop-watchdog.test.ts

@@ -60,6 +60,15 @@ function captureWith(conversationCount: number): StallCapture {
       events: null,
       deltas: null,
       disk: null,
+      processes: [
+        ...Array.from({ length: 6 }, (_, i) => ({
+          pid: 100 + i,
+          name: i === 0 ? "memory-worker" : `chrome-${i}`,
+          cpuPct: 150 - i * 10,
+          rssMb: 800,
+        })),
+        { pid: 1, name: "daemon", cpuPct: 4, rssMb: 900 },
+      ],
       activeConversations: Array.from(
         { length: conversationCount },
         (_, i) => ({
@@ -236,6 +245,16 @@ describe("buildBlockTelemetryDetail", () => {
     expect(detail.stall_capture!.waitState!.epoll!.pipes).toBe(1);
     expect(detail.stall_capture!.waitState!.children).toHaveLength(1);
     expect(detail.activity.length).toBeGreaterThanOrEqual(4);
+    expect(
+      detail.stall_capture!.sample.processes!.length,
+    ).toBeGreaterThanOrEqual(3);
+    expect(detail.stall_capture!.sample.processes![0]!.name).toBe(
+      "memory-worker",
+    );
+    // Trimming keeps the daemon for comparison.
+    expect(
+      detail.stall_capture!.sample.processes!.some((p) => p.name === "daemon"),
+    ).toBe(true);
     expect(detail.activity[0]).toMatchObject({
       kind: "turn",
       conversationType: "standard",

package/src/daemon/event-loop-watchdog.ts

@@ -124,8 +124,9 @@ type BlockTelemetryDetail = {
 
 /**
  * Ordered steps that shrink an oversize report, least diagnostic loss first.
- * The activity groups, the newest section-trail entries, and the capture's
- * wait state are what attribute a block, so they go last.
+ * The activity groups, the busiest processes, the newest section-trail
+ * entries, and the capture's wait state are what attribute a block, so they
+ * go last.
  */
 const TRIM_STEPS: Array<{
   name: string;
@@ -175,6 +176,19 @@ const TRIM_STEPS: Array<{
       d.section_trail = d.section_trail.slice(0, 3);
     },
   },
+  {
+    // Keeps the daemon, which the sampler always lists last, for comparison.
+    name: "processes_3",
+    apply: (d) => {
+      const processes = d.stall_capture?.sample.processes;
+      if (processes) {
+        const daemon = processes.find((p) => p.name === "daemon");
+        const kept = processes.slice(0, 3);
+        d.stall_capture!.sample.processes =
+          daemon && !kept.includes(daemon) ? [...kept, daemon] : kept;
+      }
+    },
+  },
   {
     name: "activity_4",
     apply: (d) => {

package/src/monitoring/__tests__/proc-fixtures.ts

@@ -0,0 +1,28 @@
+/** Fixture builders for tests that read a fake `/proc` tree. */
+
+/** A `/proc/<pid>/stat` line; times in clock ticks, rss in pages. */
+export function stat(
+  pid: number,
+  comm: string,
+  state: string,
+  ppid: number,
+  startTicks: number,
+  usage: { utime?: number; stime?: number; rssPages?: number } = {},
+): string {
+  // Fields 3..24: state ppid pgrp session tty tpgid flags minflt cminflt
+  // majflt cmajflt utime stime cutime cstime priority nice threads
+  // itrealvalue starttime vsize rss, then rsslim.
+  const fields = [
+    state,
+    ppid,
+    ...Array(9).fill(0),
+    usage.utime ?? 0,
+    usage.stime ?? 0,
+    ...Array(6).fill(0),
+    startTicks,
+    0,
+    usage.rssPages ?? 0,
+    0,
+  ];
+  return `${pid} (${comm}) ${fields.join(" ")}\n`;
+}

package/src/monitoring/__tests__/proc-wait-state.test.ts

@@ -23,6 +23,7 @@ import {
   parseProcSyscall,
   readStallWaitState,
 } from "../proc-wait-state.js";
+import { stat } from "./proc-fixtures.js";
 
 const DAEMON = 100;
 const EPFD = 7;
@@ -41,18 +42,6 @@ function fdLink(pid: number, fd: number, target: string): void {
   symlinkSync(target, join(dir, String(fd)));
 }
 
-/** A `/proc/<pid>/stat` line: state, ppid, and start time in clock ticks. */
-function stat(
-  pid: number,
-  comm: string,
-  state: string,
-  ppid: number,
-  startTicks: number,
-): string {
-  const fields = [state, ppid, ...Array(17).fill(0), startTicks, 0];
-  return `${pid} (${comm}) ${fields.join(" ")}\n`;
-}
-
 /**
  * A daemon whose main thread waits in epoll_wait (x64 syscall 232) on
  * `EPFD`, which watches the given fds.
@@ -201,11 +190,21 @@ describe("readStallWaitState", () => {
 
 describe("parsers", () => {
   test("parseProcStat handles a comm containing spaces and parentheses", () => {
-    expect(parseProcStat(stat(5, "Bun (Pool) 1", "D", 4, 42))).toEqual({
+    expect(
+      parseProcStat(
+        stat(5, "Bun (Pool) 1", "D", 4, 42, {
+          utime: 7,
+          stime: 3,
+          rssPages: 9,
+        }),
+      ),
+    ).toEqual({
       comm: "Bun (Pool) 1",
       state: "D",
       ppid: 4,
+      cpuTicks: 10,
       startTicks: 42,
+      rssPages: 9,
     });
     expect(parseProcStat("garbage")).toBeNull();
   });

package/src/monitoring/__tests__/process-usage.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Tests for the per-process CPU and memory tracker, against a fixture proc
+ * tree. CPU is a rate between two scans, so each test writes counters, scans,
+ * advances the counters, and scans again.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { readKernelPageSizeBytes } from "../proc-wait-state.js";
+import { createProcessUsageTracker } from "../process-usage.js";
+import { stat } from "./proc-fixtures.js";
+
+const DAEMON = 1;
+const MB_PAGES = 256; // 1 MiB in 4 KiB pages
+
+let procRoot: string;
+
+function writeProcess(
+  pid: number,
+  comm: string,
+  cpuTicks: number,
+  opts: { startTicks?: number; rssMb?: number; cmdline?: string[] } = {},
+): void {
+  const dir = join(procRoot, String(pid));
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "stat"),
+    stat(pid, comm, "S", 0, opts.startTicks ?? 100, {
+      utime: cpuTicks,
+      rssPages: (opts.rssMb ?? 10) * MB_PAGES,
+    }),
+  );
+  writeFileSync(join(dir, "cmdline"), (opts.cmdline ?? [comm]).join("\0"));
+}
+
+beforeEach(() => {
+  procRoot = mkdtempSync(join(tmpdir(), "process-usage-"));
+});
+
+afterEach(() => {
+  rmSync(procRoot, { recursive: true, force: true });
+});
+
+describe("createProcessUsageTracker", () => {
+  test("reports CPU as a rate between two scans, busiest first", () => {
+    // GIVEN a daemon and a memory worker
+    const tracker = createProcessUsageTracker({ procRoot });
+    writeProcess(DAEMON, "bun", 1_000, { rssMb: 900 });
+    writeProcess(20, "bun", 5_000, {
+      rssMb: 1_200,
+      cmdline: [
+        "bun",
+        "--smol",
+        "run",
+        "/app/src/plugins/defaults/memory/worker.ts",
+      ],
+    });
+
+    // WHEN the first scan runs
+    // THEN there is no rate yet
+    expect(tracker.sample(0, DAEMON)).toBeNull();
+
+    // WHEN 2s later the worker used 3 CPU-seconds and the daemon 0.1s
+    writeProcess(DAEMON, "bun", 1_010, { rssMb: 900 });
+    writeProcess(20, "bun", 5_300, {
+      rssMb: 1_200,
+      cmdline: [
+        "bun",
+        "--smol",
+        "run",
+        "/app/src/plugins/defaults/memory/worker.ts",
+      ],
+    });
+    const usage = tracker.sample(2_000, DAEMON);
+
+    // THEN the worker shows 150% of a core and leads the list
+    expect(usage).toEqual([
+      { pid: 20, name: "memory-worker", cpuPct: 150, rssMb: 1_200 },
+      { pid: DAEMON, name: "daemon", cpuPct: 5, rssMb: 900 },
+    ]);
+  });
+
+  test("never reports command-line arguments", () => {
+    // GIVEN a process started with a secret on its command line
+    const tracker = createProcessUsageTracker({ procRoot });
+    const cmdline = ["bun", "run", "deploy", "--token=sk-secret"];
+    writeProcess(30, "bun", 0, { cmdline });
+    tracker.sample(0, DAEMON);
+    writeProcess(30, "bun", 100, { cmdline });
+
+    // WHEN it is reported
+    const usage = tracker.sample(1_000, DAEMON)!;
+
+    // THEN only the kernel comm is used
+    expect(usage[0]!.name).toBe("bun");
+    expect(JSON.stringify(usage)).not.toContain("secret");
+  });
+
+  test("a reused pid is not given its predecessor's counters", () => {
+    // GIVEN pid 40 exits and a new process takes the pid
+    const tracker = createProcessUsageTracker({ procRoot });
+    writeProcess(40, "old", 9_000, { startTicks: 100 });
+    tracker.sample(0, DAEMON);
+    writeProcess(40, "chromium", 50, { startTicks: 500 });
+
+    // WHEN the next scan runs
+    const usage = tracker.sample(1_000, DAEMON)!;
+
+    // THEN the new process is skipped until it has two readings
+    expect(usage).toEqual([]);
+  });
+
+  test("the daemon is kept even when it is not among the busiest", () => {
+    // GIVEN seven busy processes and an idle, small daemon
+    const tracker = createProcessUsageTracker({ procRoot });
+    writeProcess(DAEMON, "bun", 0, { rssMb: 1 });
+    for (let pid = 50; pid < 57; pid++) {
+      writeProcess(pid, `chrome-${pid}`, 0);
+    }
+    tracker.sample(0, DAEMON);
+    writeProcess(DAEMON, "bun", 0, { rssMb: 1 });
+    for (let pid = 50; pid < 57; pid++) {
+      writeProcess(pid, `chrome-${pid}`, 100);
+    }
+
+    // WHEN the next scan runs
+    const usage = tracker.sample(1_000, DAEMON)!;
+
+    // THEN four by CPU, two by memory, plus the daemon are reported
+    expect(usage).toHaveLength(7);
+    expect(usage.at(-1)).toMatchObject({ name: "daemon", cpuPct: 0 });
+  });
+
+  test("scans at most once per interval and reuses the last result", () => {
+    // GIVEN two completed scans
+    const tracker = createProcessUsageTracker({ procRoot });
+    writeProcess(DAEMON, "bun", 0);
+    tracker.sample(0, DAEMON);
+    writeProcess(DAEMON, "bun", 50);
+    const first = tracker.sample(1_000, DAEMON);
+
+    // WHEN a tick arrives 250ms later with new counters
+    writeProcess(DAEMON, "bun", 999);
+    const again = tracker.sample(1_250, DAEMON);
+
+    // THEN the previous result is reused, not rescanned
+    expect(again).toBe(first);
+  });
+
+  test("an unreadable /proc yields null", () => {
+    const tracker = createProcessUsageTracker({
+      procRoot: join(procRoot, "missing"),
+    });
+    expect(tracker.sample(0, DAEMON)).toBeNull();
+    expect(tracker.sample(2_000, DAEMON)).toBeNull();
+  });
+
+  test("only allowlisted worker scripts get a worker label", () => {
+    // GIVEN the real schedule worker and a user script shaped like a worker
+    const tracker = createProcessUsageTracker({ procRoot });
+    const schedule = ["bun", "run", "/app/assistant/src/schedule/worker.ts"];
+    const lookalike = ["bun", "run", "/home/me/acme-payroll-worker.ts"];
+    writeProcess(60, "bun", 0, { cmdline: schedule });
+    writeProcess(61, "bun", 0, { cmdline: lookalike });
+    tracker.sample(0, DAEMON);
+    writeProcess(60, "bun", 20, { cmdline: schedule });
+    writeProcess(61, "bun", 10, { cmdline: lookalike });
+
+    // WHEN they are reported
+    const names = tracker.sample(1_000, DAEMON)!.map((p) => p.name);
+
+    // THEN the look-alike falls back to the kernel comm
+    expect(names).toEqual(["schedule-worker", "bun"]);
+  });
+
+  test("an idle process holding the most memory is still reported", () => {
+    // GIVEN six small busy processes and an idle, memory-heavy one
+    const tracker = createProcessUsageTracker({ procRoot });
+    for (let pid = 70; pid < 76; pid++) {
+      writeProcess(pid, `busy-${pid}`, 0, { rssMb: 5 });
+    }
+    writeProcess(80, "qdrant", 0, { rssMb: 2_000 });
+    tracker.sample(0, DAEMON);
+    for (let pid = 70; pid < 76; pid++) {
+      writeProcess(pid, `busy-${pid}`, 10, { rssMb: 5 });
+    }
+    writeProcess(80, "qdrant", 0, { rssMb: 2_000 });
+
+    // WHEN the next scan runs
+    const usage = tracker.sample(1_000, DAEMON)!;
+
+    // THEN the memory-heavy process takes a memory slot
+    expect(usage).toContainEqual({
+      pid: 80,
+      name: "qdrant",
+      cpuPct: 0,
+      rssMb: 2_000,
+    });
+  });
+
+  test("converts resident pages with the kernel's page size", () => {
+    // GIVEN a 64 KiB-page kernel and a process with 16384 resident pages
+    const tracker = createProcessUsageTracker({
+      procRoot,
+      pageSizeBytes: 65_536,
+    });
+    writeProcess(90, "bun", 0, { rssMb: 256 }); // 256 * 256 = 65536 pages
+    tracker.sample(0, DAEMON);
+    writeProcess(90, "bun", 0, { rssMb: 256 });
+
+    // WHEN it is reported
+    const usage = tracker.sample(1_000, DAEMON)!;
+
+    // THEN RSS is 16x what a 4 KiB assumption would give
+    expect(usage[0]!.rssMb).toBe(4_096);
+  });
+});
+
+describe("readKernelPageSizeBytes", () => {
+  function writeSelf(rssKb: number, rssPages: number): void {
+    const dir = join(procRoot, "self");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "status"), `Name:\tbun\nVmRSS:\t  ${rssKb} kB\n`);
+    writeFileSync(join(dir, "statm"), `9000 ${rssPages} 100 1 0 500 0\n`);
+  }
+
+  test("derives 64 KiB from resident kB and pages", () => {
+    writeSelf(65_536, 1_024);
+    expect(readKernelPageSizeBytes(procRoot)).toBe(65_536);
+  });
+
+  test("snaps a slightly skewed reading to the nearest page size", () => {
+    writeSelf(4_100, 1_000);
+    expect(readKernelPageSizeBytes(procRoot)).toBe(4_096);
+  });
+
+  test("falls back to 4 KiB when /proc/self is unreadable", () => {
+    expect(readKernelPageSizeBytes(procRoot)).toBe(4_096);
+  });
+});

package/src/monitoring/proc-wait-state.ts

@@ -28,8 +28,37 @@ import { join } from "node:path";
 const MAX_CHILDREN = 5;
 const MAX_THREAD_GROUPS = 8;
 
-/** Linux USER_HZ; `/proc/<pid>/stat` start times are in these ticks. */
-const CLOCK_TICKS_PER_SECOND = 100;
+/** Linux USER_HZ; `/proc/<pid>/stat` times are in these ticks. */
+export const CLOCK_TICKS_PER_SECOND = 100;
+
+/** Page sizes Linux kernels use; `/proc` page counts are in one of these. */
+const KERNEL_PAGE_SIZES = [4096, 16384, 65536] as const;
+
+/**
+ * The kernel page size, which `/proc/<pid>/stat` rss and `statm` counts are
+ * in. It varies by kernel (arm64 kernels can use 16 or 64 KiB), so it is
+ * derived from this process's own resident size, reported both in kB
+ * (`status` VmRSS) and in pages (`statm`). Falls back to 4 KiB.
+ */
+export function readKernelPageSizeBytes(procRoot = "/proc"): number {
+  const status = readText(join(procRoot, "self", "status"));
+  const statm = readText(join(procRoot, "self", "statm"));
+  const rssKb = status
+    ? Number(/^VmRSS:\s+(\d+)\s+kB/m.exec(status)?.[1])
+    : NaN;
+  const rssPages = statm ? Number(statm.trim().split(/\s+/)[1]) : NaN;
+  if (!(rssKb > 0) || !(rssPages > 0)) {
+    return KERNEL_PAGE_SIZES[0];
+  }
+  const measured = (rssKb * 1024) / rssPages;
+  // The two files are read at slightly different moments; snap to the
+  // nearest real page size.
+  return KERNEL_PAGE_SIZES.reduce((best, size) =>
+    Math.abs(Math.log2(size / measured)) < Math.abs(Math.log2(best / measured))
+      ? size
+      : best,
+  );
+}
 
 /** What `/proc/<pid>/fd/<n>` links to for an epoll instance. */
 const EPOLL_FD_LINK = "anon_inode:[eventpoll]";
@@ -99,30 +128,48 @@ function listNumericDirs(path: string): number[] {
   }
 }
 
+export interface ProcStat {
+  comm: string;
+  state: string;
+  ppid: number;
+  /** User plus system CPU time consumed, in clock ticks. */
+  cpuTicks: number;
+  /** Start time after boot, in clock ticks. */
+  startTicks: number;
+  /** Resident set size, in pages. */
+  rssPages: number;
+}
+
 /** Parse `/proc/<pid>/stat` around the parenthesised comm, which may contain spaces. */
-export function parseProcStat(
-  raw: string,
-): { comm: string; state: string; ppid: number; startTicks: number } | null {
+export function parseProcStat(raw: string): ProcStat | null {
   const open = raw.indexOf("(");
   const close = raw.lastIndexOf(")");
   if (open < 0 || close < open) {
     return null;
   }
-  // Fields after the comm start at field 3 (state); starttime is field 22.
+  // Fields after the comm start at field 3 (state), so field N is at index
+  // N - 3: utime 14, stime 15, starttime 22, rss 24.
   const fields = raw
     .slice(close + 1)
     .trim()
     .split(/\s+/);
   const ppid = Number(fields[1]);
+  const cpuTicks = Number(fields[11]) + Number(fields[12]);
   const startTicks = Number(fields[19]);
-  if (!fields[0] || !Number.isFinite(ppid) || !Number.isFinite(startTicks)) {
+  const rssPages = Number(fields[21]);
+  if (
+    !fields[0] ||
+    ![ppid, cpuTicks, startTicks, rssPages].every(Number.isFinite)
+  ) {
     return null;
   }
   return {
     comm: raw.slice(open + 1, close),
     state: fields[0],
     ppid,
+    cpuTicks,
     startTicks,
+    rssPages,
   };
 }
 

package/src/monitoring/process-memory.ts

@@ -17,9 +17,10 @@ import {
   type ProcessTableRow,
 } from "../util/process-table.js";
 import { deriveName, readProcessCommand } from "../util/process-tree.js";
+import { readKernelPageSizeBytes } from "./proc-wait-state.js";
 
-/** Linux page size assumed when converting `/proc/<pid>/statm` pages to bytes. */
-const PAGE_SIZE_BYTES = 4096;
+/** Kernel page size for `/proc/<pid>/statm` pages, read on first use. */
+let pageSizeBytes: number | undefined;
 
 export interface SmapsRollup {
   rssBytes: number | null;
@@ -74,7 +75,7 @@ function readProcessMemory(pid: number): SmapsRollup | null {
       return null;
     }
     return {
-      rssBytes: residentPages * PAGE_SIZE_BYTES,
+      rssBytes: residentPages * (pageSizeBytes ??= readKernelPageSizeBytes()),
       pssBytes: null,
       pssAnonBytes: null,
       pssFileBytes: null,

package/src/monitoring/process-usage.ts

@@ -0,0 +1,215 @@
+/**
+ * Per-process CPU and memory in the assistant container, sampled by the
+ * resource monitor.
+ *
+ * The cgroup counters show that the container hit its CPU quota or filled
+ * its memory, not which process did it. Background work can slow the
+ * daemon without blocking its event loop: a worker, Qdrant, or a browser
+ * uses the container's shared CPU while the daemon waits for a turn on it.
+ * This tracker names the processes using the container's resources, so a
+ * slow daemon can be told apart from a starved one.
+ *
+ * CPU is a rate, so it needs two readings: each scan reads every process's
+ * cumulative CPU ticks from `/proc/<pid>/stat` and compares them with the
+ * previous scan. Memory is the resident set size from the same file.
+ *
+ * Names are metadata only: the daemon is "daemon", the assistant's own
+ * worker scripts use a fixed label from an allowlist, and any other process
+ * uses its kernel `comm` (15 bytes, no arguments). Command-line content never
+ * leaves the machine.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  CLOCK_TICKS_PER_SECOND,
+  parseProcStat,
+  readKernelPageSizeBytes,
+} from "./proc-wait-state.js";
+
+/** Processes reported by CPU, busiest first. */
+const TOP_BY_CPU = 4;
+/** Further processes reported by resident memory, largest first. */
+const TOP_BY_MEMORY = 2;
+/** Minimum time between scans; a shorter tick reuses the last result. */
+const DEFAULT_MIN_SCAN_INTERVAL_MS = 1_000;
+
+/**
+ * The assistant's own worker scripts, matched on the trailing path of a
+ * command-line argument. Only these fixed labels are ever reported; any
+ * other process is named by its kernel comm.
+ */
+const KNOWN_WORKERS: ReadonlyArray<{ pattern: RegExp; name: string }> = [
+  {
+    pattern: /(?:^|\/)src\/schedule\/worker\.[cm]?[jt]s$/,
+    name: "schedule-worker",
+  },
+  {
+    pattern: /(?:^|\/)defaults\/memory\/worker\.[cm]?[jt]s$/,
+    name: "memory-worker",
+  },
+  {
+    pattern: /(?:^|\/)src\/monitoring\/worker\.[cm]?[jt]s$/,
+    name: "monitoring-worker",
+  },
+  {
+    pattern: /(?:^|\/)src\/routes\/worker\.[cm]?[jt]s$/,
+    name: "routes-worker",
+  },
+  { pattern: /(?:^|\/)embed-worker\.mjs$/, name: "embed-worker" },
+  { pattern: /(?:^|\/)rerank-worker\.mjs$/, name: "rerank-worker" },
+];
+
+export interface ProcessUsage {
+  pid: number;
+  /** "daemon", an assistant worker name, or the kernel comm. */
+  name: string;
+  /** CPU used since the previous scan, as a percentage of one core. */
+  cpuPct: number;
+  rssMb: number;
+}
+
+interface ProcessCounters {
+  cpuTicks: number;
+  startTicks: number;
+}
+
+export interface ProcessUsageTracker {
+  /**
+   * Busiest processes since the previous scan, or null before the first
+   * two scans complete or when `/proc` is unreadable. `nowMs` must be read
+   * at the call, so the time between scans matches the counters' interval.
+   */
+  sample(nowMs: number, daemonPid: number | null): ProcessUsage[] | null;
+}
+
+function readText(path: string): string | null {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** A telemetry-safe name: never includes command-line arguments. */
+function processName(
+  procRoot: string,
+  pid: number,
+  comm: string,
+  daemonPid: number | null,
+): string {
+  if (pid === daemonPid) {
+    return "daemon";
+  }
+  const cmdline = readText(join(procRoot, String(pid), "cmdline"));
+  for (const arg of cmdline?.split("\0") ?? []) {
+    const path = arg.replaceAll("\\", "/");
+    const worker = KNOWN_WORKERS.find(({ pattern }) => pattern.test(path));
+    if (worker) {
+      return worker.name;
+    }
+  }
+  return comm;
+}
+
+export function createProcessUsageTracker(
+  options: {
+    procRoot?: string;
+    minScanIntervalMs?: number;
+    pageSizeBytes?: number;
+  } = {},
+): ProcessUsageTracker {
+  const procRoot = options.procRoot ?? "/proc";
+  const pageSizeBytes =
+    options.pageSizeBytes ?? readKernelPageSizeBytes(procRoot);
+  const minScanIntervalMs =
+    options.minScanIntervalMs ?? DEFAULT_MIN_SCAN_INTERVAL_MS;
+  let previous: Map<number, ProcessCounters> | null = null;
+  let previousAt = 0;
+  let last: ProcessUsage[] | null = null;
+
+  return {
+    sample(nowMs: number, daemonPid: number | null): ProcessUsage[] | null {
+      if (previous != null && nowMs - previousAt < minScanIntervalMs) {
+        return last;
+      }
+
+      let pids: number[];
+      try {
+        pids = readdirSync(procRoot)
+          .filter((entry) => /^\d+$/.test(entry))
+          .map(Number);
+      } catch {
+        return null;
+      }
+
+      const elapsedSeconds = (nowMs - previousAt) / 1000;
+      const current = new Map<number, ProcessCounters>();
+      const usage: Array<ProcessUsage & { comm: string }> = [];
+      for (const pid of pids) {
+        const raw = readText(join(procRoot, String(pid), "stat"));
+        const stat = raw != null ? parseProcStat(raw) : null;
+        if (stat == null) {
+          // Exited between readdir and read.
+          continue;
+        }
+        current.set(pid, {
+          cpuTicks: stat.cpuTicks,
+          startTicks: stat.startTicks,
+        });
+        const before = previous?.get(pid);
+        // A reused pid starts a new process; its old counters do not apply.
+        if (before == null || before.startTicks !== stat.startTicks) {
+          continue;
+        }
+        const cpuSeconds =
+          (stat.cpuTicks - before.cpuTicks) / CLOCK_TICKS_PER_SECOND;
+        usage.push({
+          pid,
+          comm: stat.comm,
+          name: "",
+          cpuPct:
+            elapsedSeconds > 0
+              ? Math.round((cpuSeconds / elapsedSeconds) * 100)
+              : 0,
+          rssMb: Math.round((stat.rssPages * pageSizeBytes) / (1024 * 1024)),
+        });
+      }
+
+      const hadPrevious = previous != null;
+      previous = current;
+      previousAt = nowMs;
+      if (!hadPrevious) {
+        last = null;
+        return null;
+      }
+
+      // The busiest by CPU, then the largest by memory (an idle process can
+      // still fill the cgroup), then the daemon for comparison.
+      const byCpu = [...usage].sort(
+        (a, b) => b.cpuPct - a.cpuPct || b.rssMb - a.rssMb,
+      );
+      const reported = byCpu.slice(0, TOP_BY_CPU);
+      const byMemory = [...usage].sort((a, b) => b.rssMb - a.rssMb);
+      for (const entry of byMemory) {
+        if (reported.length >= TOP_BY_CPU + TOP_BY_MEMORY) {
+          break;
+        }
+        if (!reported.includes(entry)) {
+          reported.push(entry);
+        }
+      }
+      const daemon = usage.find((entry) => entry.pid === daemonPid);
+      if (daemon && !reported.includes(daemon)) {
+        reported.push(daemon);
+      }
+      // Names are read only for the reported processes.
+      last = reported.map(({ comm, ...entry }) => ({
+        ...entry,
+        name: processName(procRoot, entry.pid, comm, daemonPid),
+      }));
+      return last;
+    },
+  };
+}

package/src/monitoring/resource-sample-types.ts

@@ -11,6 +11,7 @@ import type {
   ContainerReclaimCounters,
 } from "../util/cgroup-memory.js";
 import type { ActiveConversation } from "./active-conversations.js";
+import type { ProcessUsage } from "./process-usage.js";
 
 export interface ResourceSampleMemory {
   currentBytes: number;
@@ -68,4 +69,11 @@ export interface ResourceSample {
    * Null when nothing is processing or the database is unavailable.
    */
   activeConversations: ActiveConversation[] | null;
+  /**
+   * Busiest processes in the container since the previous process scan, so
+   * a CPU- or memory-starved daemon names what it was competing with. Null
+   * until two scans have run or where `/proc` is unreadable. Absent on
+   * samples written before this field existed.
+   */
+  processes?: ProcessUsage[] | null;
 }

package/src/monitoring/resource-sampler.ts

@@ -44,9 +44,14 @@ import {
   listProcesses,
 } from "../util/process-tree.js";
 import { readActiveConversations } from "./active-conversations.js";
+import { readDaemonHeartbeat } from "./daemon-heartbeat.js";
 import { topProcessesByFd } from "./file-descriptors.js";
 import { getTrackedDataFiles, readFileResidency } from "./page-cache.js";
 import { topProcessesByMemory } from "./process-memory.js";
+import {
+  createProcessUsageTracker,
+  type ProcessUsageTracker,
+} from "./process-usage.js";
 import { prunePrefixedJsonFiles } from "./prune-snapshots.js";
 import type {
   ResourceSample,
@@ -94,6 +99,7 @@ export function computeSampleDeltas(
 export async function takeSample(
   now: number,
   prev: ResourceSample | null = null,
+  processUsage: ProcessUsageTracker | null = null,
 ): Promise<ResourceSample> {
   const currentBytes = getContainerMemoryUsageBytes();
   const limitBytes = getContainerMemoryLimitBytes();
@@ -129,6 +135,11 @@ export async function takeSample(
         }
       : null,
     activeConversations: readActiveConversations(),
+    // Timestamped at the scan, not the tick start: the disk read above can
+    // take seconds, and the CPU rate needs the counters' real interval.
+    processes:
+      processUsage?.sample(Date.now(), readDaemonHeartbeat(now)?.pid ?? null) ??
+      null,
   };
   if (prev != null) {
     sample.deltas = computeSampleDeltas(prev, sample);
@@ -252,6 +263,7 @@ export function startResourceSampler(
   // Watches the daemon's event-loop heartbeat; captures the daemon main
   // thread's kernel state mid-stall when the heartbeat goes stale.
   const stallCapture = createStallCaptureMonitor(dataDir);
+  const processUsage = createProcessUsageTracker();
 
   // Skip ticks while a sample is in flight: the disk measurement can take
   // seconds (du over the workspace), and overlapping ticks would all delta
@@ -273,7 +285,7 @@ export function startResourceSampler(
     const now = clock();
     let sample: ResourceSample;
     try {
-      sample = await takeSample(now, prevSample);
+      sample = await takeSample(now, prevSample, processUsage);
       prevSample = sample;
       buffer.append(sample);
     } catch (err) {