Module tower_sampler 

Tower: CPU and memory per task, for the read-only task manager pane (SPEC_TOWER_TASK_MANAGER_PANE_2026_10_08.md).

A task is a pane and every process it started, plus one more for AgentMux itself. Each sample takes one process snapshot (agentmux_procstats) and groups it:

1. The pane’s tracker (process_tracker): a Job Object or cgroup on an agent, which nothing it starts can leave; a best-effort scan on macOS.
2. The pane’s process tree where there is no tracker membership (a terminal on Linux or macOS): descendants of its shell.
3. Sticky membership: a process seen in a task stays in it until it exits, even after it is reparented away from the tree.
4. AgentMux: the backend’s own ancestry while it is AgentMux’s (launcher, window host) and everything under it no task claimed.

Sampling is driven by the pane (tower.sample): nothing runs while no Tower is open, and two panes asking at once share a sample.

Structs

BlockLabel

How a block is named and what kind of task it is.

Exited 🔒

A task’s process that has exited: what it was when last seen.

Group 🔒

Grouping 🔒

Inputs

What the sampler is told about the panes.

Sampled 🔒

One measurement: the process table, every process’s CPU rate, the grouping and each task’s CPU account rate. render turns it into an answer.

State 🔒

Tower

The process-wide sampler. Its state is the previous sample (for CPU rates) and sticky membership.

Constants

AGENTMUX_TASK_ID

TowerTask::id of AgentMux’s own processes.

EXITED_LINGER 🔒

How long a task’s exited process stays listed (dimmed, with what it used): long enough to see a build’s compilers that a 2 s sample catches once or never. SPEC_TOWER_AGENT_CENTRIC_VIEWS_2026_10_08.md §5.4.

INTERVAL

How often the pane asks while it is visible.

MAX_EXITED 🔒

At most this many exited processes are kept, the newest: a big build runs thousands of compilers a minute.

MAX_TREE 🔒

Most processes one task’s tree walk takes (a fork bomb shouldn’t stall a sample).

REUSE_WITHIN 🔒

A request this soon after the last sample gets that sample: two Tower panes (or a re-render) don’t double the cost or shrink the CPU window.

SHARED_TOP

Rows a snapshot sent to another machine carries per list (busiest, largest), as a remote frame does (agentmux_remote::procs).

STALE_AFTER 🔒

A gap longer than this since the last sample starts the CPU rates over, so a pane that was hidden for minutes doesn’t show minutes-long averages.

Functions

advance 🔒

Measure: group the table, take every process’s and task account’s rate since the previous measurement, and remember sticky membership. cmdline reads a process’s command line, for labelling AgentMux’s own processes only (tower_agentmux).

block_label

A pane’s name in Tower and on its stats badge: the agent’s name, else what the terminal runs. None for a block that no longer exists.

group 🔒

Group a snapshot into tasks (module doc). Pure: everything it needs is in its arguments.

is_agentmux_process 🔒

keep_top 🔒

Keep the top busiest by CPU and the top largest by memory (their union, in their original order).

proc_id 🔒

render 🔒

The answer from a measurement. Pure apart from labels and renderer.

renderer_suffix 🔒

What a renderer row adds after its type: the window or pane it serves.

share

Make a snapshot fit to send to a paired device: drop the tasks hidden names (an agent hidden from paired devices) and their processes, keep the host rows matching every word of filter, then only the top busiest and top largest of those. Totals keep counting every process.

sum_known 🔒

A sum of rates, or None when none of them is known yet (a first sample), never a made-up 0.

track_peaks_and_exits 🔒

Update each process’s peak memory, and note the tasks’ members that were in the previous measurement and are gone from this one. Returns the peaks by index and the exited processes still within EXITED_LINGER.

tracking_label 🔒