@spec build_parent_map(struct()) :: %{required(String.t()) => struct()}

Builds a map from child agent name to parent agent.

@spec find_agent(
  struct(),
  String.t()
) :: {:ok, struct()} | :error

Finds an agent by name using depth-first search.

Returns {:ok, agent} if found, :error otherwise.

@spec validate_unique_names(struct()) :: {:ok, MapSet.t()} | {:error, String.t()}

Validates that all agent names in the tree are unique.

Returns {:ok, names} where names is the set of all names, or {:error, reason} if duplicates are found.