@spec active_worker_action(map() | nil) :: String.t() | nil

What the currently-running worker is doing, for the main streaming line.

While a worker runs — often many minutes — the orchestrator's own action is just "running spawn_agent…", which says nothing. The useful detail lives on AgentInfo but was only rendered in the Overview tab, so following a run meant switching tabs or reading the log.

The DEEPEST running agent is the informative one: a parent that spawned a child is only waiting on it.

@spec assign_session_list(
  Phoenix.LiveView.Socket.t(),
  (String.t() | nil -> [map()]),
  :auto | :keep
) :: Phoenix.LiveView.Socket.t()

Populate the sidebar's session list for the current working directory.

The list used to be built ONLY by open_cwd and toggle_sessions, so opening a session by URL (or reloading the page on one) left sessions at its mount default of [] — an empty sidebar that had simply never been asked to build itself.

visibility is :auto on a first load (open the panel when there is something to show) or :keep on a refresh, which must never open a panel the user closed nor close one they opened. lister takes the cwd and returns the headers (injected so this is testable without the filesystem).

@spec restore_details_stream(map()) :: map()

Recover tool rows that the durable save dropped, using each turn's ex_snapshot as the authority for what it actually ran.

A turn's tool history is persisted twice and inconsistently. The live LiveView writes tool_events; Sessions.persist_run_result/3 — the durable path, which runs whether or not a browser is attached — hardcodes tool_events: []. Reloading mid-run resets details_stream and rebuilds it from that empty field, so everything before the reload is lost and the truncated stream is written back over the full one. Each reload erodes it further.

The full transcript survives regardless, because ex_snapshot holds the run's ExAthena.Messages verbatim. A real 23-iteration run (a3b95452ca35) kept 31 tool calls there while details_stream had 3, and its entire second turn had none — 16 delegated workers rendered as one line of prose.

Only calls absent from the stream are added, so a complete turn is returned untouched and re-running this is a no-op.

@spec restore_open_turn(map()) :: map()

Reopen an assistant turn whose run never finished.

Details are stamped with the assistant message's id from the first event onward, but the message itself was only appended when the run COMPLETED. A run that was killed, crashed, or is still in flight therefore leaves its details parented to a message that does not exist — and message_items/2 matches on message_id, so every one of them renders nowhere. A session holding 118 saved entries opened as a blank screen.

This synthesises the missing message from the details themselves, so an interrupted run shows the work it did instead of nothing.

@spec session_payload(map()) :: map()

The map persisted for a session.

Includes the orchestrator snapshot: the Overview tab is fed by the Coordinator, which lives only in memory and is only re-subscribed while a run is still attachable. Without this, reloading the page after a run ended (or after a server restart) showed a blank Overview even though the whole run was on disk.

@spec session_signature(map()) :: integer()

Cheap fingerprint of everything save_session/1 persists that can change mid-run. Compared against the last saved value so the tick only writes when the session actually moved.

Hashes the whole structure rather than counting entries: content and thinking deltas EXTEND an existing details_stream entry instead of prepending a new one, so a length check would miss a streaming answer.

@spec stored_orchestrator(map()) :: map() | nil

The orchestrator snapshot stored with a session, if any.

@spec token_summary(map() | nil) :: map() | nil

Split a run's token use between the orchestrator and its workers.

Per-agent totals are already tracked on AgentInfo and shown per row, but nothing aggregated them. The split is the interesting number: the orchestrator's context stays small by design (workers return summaries, not transcripts), so a large worker total against a small orchestrator total is the architecture behaving, not a leak.

Nested subagents are counted with the workers — the agent list is flat and every depth carries its own usage.

@spec upsert_message([map()], map()) :: [map()]

Append msg, or replace the existing message with the same id.

restore_open_turn/1 may already have put a placeholder for the in-flight turn into the list (a reload mid-run), and a blind append would then leave two messages sharing an id — a duplicate DOM id, which LiveView raises on.