Module tree 

The supervision tree — the in-memory record of the subagent process tree.

This module owns the bookkeeping: who spawned whom, each node’s depth and agent_path, hierarchical token accounting to the root, the tree-wide draining flag, and the spawn chokepoint that enforces the fork-bomb caps. It is pure logic — no processes, pipes, or signals (those are spawn.rs/reap.rs/kill.rs). Depth is minted here from the parent’s record, never trusted from a child’s request: a child that could name its own depth could name 0 forever and defeat the recursion cap.

Structs

Caps

Fork-bomb / runaway-recursion caps, enforced at the one spawn chokepoint. Conservative defaults; a spawn exceeding any of these is refused as a tool result, never a crash — the requesting agent gets to adapt, and one greedy branch cannot take the tree down.

Node

NodeId

Stable per-tree node id (the root is 0).

TokenBucket

A std-only token bucket for the tree-wide spawn-rate cap (8 burst, 2 tokens/s by default). Hand-rolled — a rate limiter is Instant + arithmetic, never a crate. Refill is lazy: every try_take first credits the tokens that have accrued since the last call, then spends one if it can. This catches a fast churn loop that stays under the absolute subagent count — a wedged child hammering subagent.spawn just keeps getting refusals.

Tree

Enums

NodeStatus

SpawnRefused

Why a spawn was refused. Surfaced to the requesting agent as a tool result so its model can adapt — not an error that crashes the tree.

Functions

parse_rate

Parse "<burst>/<per>s" — ONE rate spelling across the config surface (a2a.principals[].quotas.rate, webhook rate, step rate). Returns (burst, window seconds).