Module scan 

Finding an agent’s processes in the process table, by the env tag they inherit. Two uses:

• tagged, on every OS: after a teardown, what still carries the tag got out of the agent’s tracker, and is reported (agent_teardown).
• ScanTracker: the best-effort tracker where the OS can’t hold the tree: macOS (no cgroups), Linux without a delegated cgroup, and Windows when a Job Object can’t be created.

An agent’s processes are:

• every descendant of the processes assigned to it (its CLI), and
• every process carrying its AGENTMUX_BLOCKID in its environment, which whatever the agent starts inherits, setsid daemons and orphans reparented to init or launchd included, plus their descendants.

A process that cleared its environment after leaving the tree is missed; hence BestEffort. See docs/analysis/agent-spawned-process-tracking-2026-10-07.md §6.3.

Structs

Inner 🔒

ScanTracker

One agent’s best-effort tracker.

Snapshot 🔒

Constants

SNAPSHOT_TTL 🔒

A process-table snapshot shared by every scan tracker, refreshed at most this often: the 2 s poll of N agents costs one OS scan, not N.

Statics

SNAPSHOT 🔒

Functions

ask_to_exit 🔒

Ask pid to exit. false where there is no such signal (Windows: the agent side runs without a console, so no CTRL_BREAK).

block_tag

The env entry that marks a block’s processes.

is_root 🔒

kill_now 🔒

members_in 🔒

The members of one agent’s tree in sys: its live roots (PID → start time) and every process whose environment holds tag (AGENTMUX_BLOCKID=<block>), then all their descendants. Never srv itself.

same_process 🔒

Is p the process recorded as started at started_ms? A PID the OS has reused for another process is not (start times are whole seconds).

tagged

Every live process tagged with block_id (and its descendants), from a fresh scan. What a teardown reports as having escaped its tracker.

with_snapshot 🔒

Run f over a snapshot of the process table, environments and command lines included, taken no earlier than after (when given) and no older than SNAPSHOT_TTL. Callers waiting on the lock share the scan the first of them takes.