Trait TrackerHandle

Source

pub trait TrackerHandle: Send + Sync {
    // Required methods
    fn assign_process(&self, pid: u32) -> Result<(), String>;
    fn list_members(&self) -> Vec<TrackedProcess>;
    fn kill_tree(&self);
    fn kill_pid(&self, pid: u32) -> bool;
    fn confidence(&self) -> TrackingConfidence;

    // Provided methods
    fn set_below_normal_priority(&self, _on: bool) -> Result<(), String> { ... }
    fn terminate(&self) -> bool { ... }
    fn member_count(&self) -> usize { ... }
    fn member_pids(&self) -> Vec<u32> { ... }
    fn cpu_time_ns(&self) -> Option<u64> { ... }
    fn spawn_target(&self) -> Option<PathBuf> { ... }
}

Expand description

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.

Required Methods§

Source

fn assign_process(&self, pid: u32) -> Result<(), String>

Add a freshly-spawned process to the tracked tree. Called by the controller immediately after tokio::process::Command::spawn. Descendants created AFTER this call are caught automatically; descendants created BEFORE (in the ~1ms race window) escape. No-op in the stub impl — platforms without a real tracker silently accept the PID and move on.

Source

fn list_members(&self) -> Vec<TrackedProcess>

Enumerate the current members of this tracked tree.

Must be cheap enough to poll every ~2s. On Windows this is a single Job Object query; the planned Linux and macOS impls would read cgroup.procs and scan sysctl respectively.

Source

fn kill_tree(&self)

Forcibly terminate every process in this tracked tree.

Source

fn kill_pid(&self, pid: u32) -> bool

Terminate a single process by PID, if it’s a member of this tree. Returns true if the PID was known and the kill was attempted.

Source

fn confidence(&self) -> TrackingConfidence

Describes how confidently this platform tracks descendants. Surfaced to the UI so the user can tell when tracking is best-effort and escape-prone.

Provided Methods§

Source

fn set_below_normal_priority(&self, _on: bool) -> Result<(), String>

Run every process in this tree at below-normal CPU priority (on), or back at normal. Descendants inherit it and cannot raise it themselves. Windows only (a Job Object priority-class limit); a no-op elsewhere. See docs/analysis/ANALYSIS_SRV_HTTP_STALL_IO_DRIVER_STARVATION_2026_09_26.md §8.3.

Source

fn terminate(&self) -> bool

Ask every member to exit (SIGTERM): the graceful step a teardown takes before kill_tree. false where the platform has no graceful signal for a whole tree yet (Windows), so there is nothing to wait for.

Source

fn member_count(&self) -> usize

How many processes the tree holds right now, the agent’s own CLI and plumbing included: what a teardown waits to reach zero.

Source

fn member_pids(&self) -> Vec<u32>

The tree’s PIDs alone, plumbing included, without the per-process enrichment list_members does: what Tower reads every refresh (SPEC_TOWER_TASK_MANAGER_PANE_2026_10_08.md §5).

Source

fn cpu_time_ns(&self) -> Option<u64>

CPU time the whole tree has used, in nanoseconds, including members that have exited (a Job Object’s accounting, a cgroup’s cpu.stat), so a burst of short-lived build processes isn’t lost between two samples. None where the platform keeps no such account.

Source

fn spawn_target(&self) -> Option<PathBuf>

Where a child about to be spawned joins the tree before it execs (Linux: the cgroup’s cgroup.procs), so nothing it forks can slip out between spawn and assign_process. None: only the after-spawn assignment.