@spec broadcast([session()], binary()) :: :ok

Send the same prompt to all sessions.

@spec collect([session()], pos_integer()) ::
  [{session(), result_message()}] | {:timeout, [{session(), result_message()}]}

Wait for all sessions to produce a result message.

Subscribes to each session and collects {:result, _, _} messages. Returns a list of {session_pid, result_message} tuples, or {:timeout, partial_results} if the deadline is reached first.

A session that broadcasts a terminal message instead of a result -- it exited, expired, or hit :line_too_large -- is dropped from the wait set rather than waited out, since it can never produce one. Such a session is simply absent from the returned list, so the list can be shorter than sessions.

Results are matched by turn. Session.subscribe/1 replays history, so a session already carrying a finished turn would otherwise hand the collector that old result the instant it attached -- returning stale data for a turn still in flight. Each session's Session.current_turn/1 is read before subscribing, and only results stamped with that turn or later are accepted.

@spec healthy?() :: boolean()

Returns true if the session supervisor is alive and healthy.

@spec run(binary(), opts()) :: result_message() | {:error, term()}

Single-shot convenience: start a session, send prompt, collect result, stop.

@spec run_many(binary(), [opts()]) ::
  [{session(), result_message()}]
  | {:timeout, [{session(), result_message()}]}
  | {:error, term()}

Start N sessions with different options but the same prompt; collect all results.

@spec start_session(opts()) :: {:ok, session()} | {:error, term()}

Start a single session under the supervisor.

Options are passed through to CrowdControl.Session and CrowdControl.CLI.

Additional option:

• :prompt - initial prompt to send after the CLI starts

@spec start_sessions([opts()]) :: {:ok, [session()]} | {:error, [term()]}

Start multiple sessions in parallel.

Takes a list of option keyword lists. Returns {:ok, pids} if every session started, or {:error, errors} listing the failing entries.

Concurrency is clamped to the configured :max_sessions cap.

@spec stop_all([session()]) :: :ok

Stop all sessions in parallel.