Box census (who is creating processes, and where the CPU actually went)

What it is

A census of the machine itself — not of the app. It answers the questions that come up when the computer feels slow: what is starting all these processes, and what is spending the CPU?

Three things make it different from a hand-written sampler, and all three exist because of real wrong answers that reached this project's owner:

• It never identifies a process by its name alone. Windows performance tooling addresses per-process counters by process name, and those names are renumbered as processes come and go. A "rate" read that way silently compares one process against a different one that reused its slot. That is how a measurement once reported 44.9 busy cores on a 24-core machine. This census keys every process on its identifier and its start time, so two processes can never be confused.
• It watches a series of snapshots, not two. A process that starts and finishes entirely inside the measurement window appears in neither the first nor the last snapshot — a two-snapshot comparison cannot see it at all. This one walks a series, so such a process is counted both as born and as gone.
• It checks its own arithmetic before printing. Every reading is tested against what is physically possible — the processes it can still see cannot have used more CPU than the whole machine produced, and the machine cannot have produced more than one core-second per processor per second. If a check fails, the command says so loudly rather than presenting a confident number, and it exits with a distinct code so a script can tell the difference.

It also states what it cannot see: process births are always a lower bound (anything shorter than the gap between two snapshots is invisible), and one of the machine's fault counters is not maintained by current Windows at all, which the output says explicitly instead of printing a misleading zero.

Where to find it

In a terminal, from the project folder:

npm run perf:census                       # a ~10 second window, defaults
npm run perf:census -- --window=30        # a longer window
npm run perf:census -- --poll=1000        # a coarser sweep, cheaper on a loaded machine
npm run perf:census -- --top=20           # more rows in each table
npm run perf:census -- --json             # the whole measurement as JSON for another tool

There is no panel or menu entry: this is a command for whoever is investigating the machine, including other agents.

How it behaves

The run takes a little longer than the window you ask for, and the output tells you the window it actually measured rather than the one you requested. That matters: on a loaded machine a single pass over the process table costs real time (measured here at roughly a second on a machine carrying 1,744 processes), so a requested 6-second window at half-second sweeps can come back as a 20-second window. The output says which interval it achieved, and marks the reading COARSE when the achieved gap is much wider than the requested one — because a wider gap does not merely add noise, it silently drops every process shorter than the gap.

The output is grouped into: the self-checks; where the CPU went; who is being born and by which parent; the machine's own counters; each drive; and the busiest individual processes by CPU and by disk. Exit codes are 0 for a normal reading, 1 when no census could be taken at all, and 3 when a census was produced but failed its own consistency checks — a reading you should not quote.

For agents

• Entry point: npm run perf:census → scripts/ops/box-census.mts.
• The arithmetic — decoding, identity keys, aggregation and the consistency checks — is pure and unit-tested in scripts/lib/box-census.mjs, so a change there is provable without a live machine.
• It composes existing primitives rather than adding native code: parseSystemProcessInformation (src/main/process/native-process-scan-parse.ts, extended with the read/write transfer split), deriveBoxTotals (the box CPU shares), and the measured DISK_PERFORMANCE offsets the disk sampler already pins.
• It reads the process table with one in-process syscall, the box counters with two more, and one ioctl per drive. It never uses WMI, never uses typeperf, and never spawns a helper process — so it cannot deepen the load it is measuring, and it works while the machine is busy.
• Use it instead of writing a new sampler. A hand-rolled typeperf/WMI sampler is the exact mistake this command exists to end: it is not free on a loaded machine, and its numbers are wrong in a way that looks right.
• For a fast "who is using the box right now" snapshot from the running app, use perf:who. For filesystem-work attribution (which processes are hammering the disk with metadata operations), use perf:whodunit. For how many processes one agent session costs, use perf:session-footprint.

Related

• Performance Monitor — the app's own live view of the machine and the sessions, read in process from the app's logs and memory rather than measured fresh.
• Governance control and triage — what the app is currently holding back and which governor decided it, and the ordered runbook for working out why the machine is slow.