Module process_tracker 

Agent-spawned process tracking.

Gives the host a complete, authoritative view of what each agent CLI has forked — backgrounded shells, dev servers, Docker containers, file watchers, nested bash/python/node children, etc. The goal is end-user visibility: a user running multiple agents can see in one place what’s still running on their machine, and kill it reliably when they’re done.

The API is a platform-agnostic trait, one impl per platform. Terminals a person types in get the no-op StubTracker everywhere but Windows (see AgentProcessRegistry::ensure_tracker_kind).

Platform	Impl	Mechanism	Confidence
Windows	JobObjectTracker	CreateJobObject + AssignProcessToJobObject + TerminateJobObject	high
Linux	CgroupTracker	cgroup v2 per agent in srv’s delegated user scope; cgroup.procs / cgroup.kill	high
Linux, no delegated cgroup; macOS	ScanTracker	process table: descendants of the CLI + the inherited AGENTMUX_BLOCKID env tag	best effort
other	StubTracker	no-op	none

The frontend’s swarm panel surfaces the confidence level so users know when tracking may miss escaped descendants.

See docs/analysis/agent-spawned-process-tracking-2026-10-07.md.

Modules

cgroup_linux

Linux tracker: one cgroup v2 per agent, under a systemd user scope srv puts itself in at startup with Delegate=yes, so srv may create and manage cgroups below it.

registry

AgentProcessRegistry — app-wide map from block_id → tracker handle.

scan

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

stub

No-op tracker used on unsupported platforms, and on Windows when JobObjectTracker::new fails (e.g. the process is not elevated enough to create a job object). All operations succeed silently; list_members always returns empty. Confidence reports None so the UI can inform the user that tracking is disabled.

Structs

TrackedProcess

A single process tracked by the host — PID + metadata enriched per-platform. The frontend renders one row per entry.

Enums

TrackingConfidence

How reliable this platform’s tracker is.

Traits

TrackerHandle

Opaque per-agent handle returned by the tracker when we wrap a spawn. Held inside AgentProcessRegistry for the lifetime of the pane; dropped when the pane closes or the agent exits.

Functions

agent_started

Filter a tracker’s raw membership down to the processes the agent started through its tools — what the Swarm list, the pane-close confirmation and the process events should count.

image_name 🔒

Lowercased executable name without directory or .exe suffix — C:\Program Files\Git\bin\bash.exe → bash.

is_shell 🔒

Interpreters an agent runs its tool commands through (Claude Code’s Bash tool spawns bash.exe -c ... directly under claude.exe; Codex/Gemini use powershell/cmd).

new_tracker

Factory: returns a platform-appropriate tracker handle that will accept the next-spawned process and everything it forks.