galaxy/specs/review-sse-connection-strategy/TECH.md

Tech spec: scope SSE event subscriptions to open parent/child conversations

Context

OrchestrationEventStreamer (app/src/ai/blocklist/orchestration_event_streamer.rs) delivers v2 orchestration events (cross-agent messages and lifecycle events) into a conversation by holding a long-lived SSE connection per conversation. The streamer is SSE-only and gated solely on OrchestrationV2; the previous polling fallback path was removed before this change so all state and code paths described below are SSE-only.

A key semantic to keep in mind throughout: an agent run subscribes to its own run_id because that subscription is its inbox. Server-side, AgentEventDriverConfig::run_ids filters events whose run_id matches the set; for a given agent run, events with run_id == self_run_id are messages and lifecycle signals destined for that run. Both parent agent runs and child agent runs (including headless CLI children of any harness) must keep this subscription up while their run is active in order to receive messages.

Note. The "Today the lifecycle is wrong" subsection and the "Relevant code" listing below describe the pre-rewrite state of the streamer (then often called "the poller") that motivated this change. Specific identifiers, line numbers, and field names in those subsections are historical and no longer correspond to the current code. The "Proposed changes" section onwards reflects the implementation as it now exists.

Today the lifecycle is wrong in three ways:

1. Wrong start trigger. SSE only opens on the ConversationStatus::Success transition (orchestration_event_streamer.rs:229-237, start_event_delivery at line 494). A conversation that is open in the UI but still in-progress will not subscribe; conversely once it has subscribed, status no longer matters.
2. Wrong stop trigger for parents. Cleanup only runs on RemoveConversation/DeletedConversation (lines 178-193). Closing the agent view of a parent conversation does not tear down its SSE, so a parent the user has abandoned in the UI keeps a live connection.
3. Wrong scope. on_server_token_assigned (line 240) registers the conversation's own run_id for every cloud-backed conversation that gets a server token (except shared-session viewers, line 254). Solo conversations — neither parents (have spawned children) nor children (parent_conversation_id set) — are not part of an orchestration tree and cannot meaningfully receive or send orchestration events. They should not subscribe. The shared-session-viewer exclusion is also incomplete: the GUI auto-opens a viewer pane for cloud children spawned via start_agent (Conversation::is_remote_child() is true), and those placeholders look like child conversations to the predicate — they have parent_conversation_id set — even though the actual run is on a cloud worker. Without a guard they open a redundant SSE in the parent's process for events the parent's own SSE will already deliver.

There is also a related state-leak: register_watched_run_id (line 138) only inserts into watched_run_ids; nothing removes a child's run_id when the child finishes or is deleted. A long-lived parent accumulates dead run_ids and reconnects with an ever-growing filter.

Relevant code

• app/src/ai/blocklist/orchestration_event_streamer.rs — owner of watched_run_ids, sse_connections, polling/SSE timers, and all cleanup paths.
• app/src/ai/blocklist/action_model/execute/start_agent.rs:112-119 — the only external caller of register_watched_run_id, registering a child's run_id under the parent's AIConversationId when the child receives a server token.
• app/src/ai/active_agent_views_model.rs — already tracks "is this conversation expanded in any pane?" via agent_view_handles. Emits ActiveAgentViewsEvent::ConversationClosed { conversation_id } on ExitedAgentView (line 167-169) and on unregister_agent_view_controller from the pane-close path (line 200-202; see pane_group/pane/terminal_pane.rs:383-385). Helper is_conversation_open(conversation_id, ctx) (line 354) gives the cross-pane "open anywhere?" check.
• app/src/ai/agent/conversation.rs:781-792 — parent_conversation_id() and is_child_agent_conversation() classify a conversation as child or non-child; combined with the poller's own watched_run_ids set these classify a conversation as parent/child/solo.
• app/src/ai/agent_events/driver.rs (38-50, 177-199) — AgentEventDriverConfig::run_ids is forwarded to ServerApi::stream_agent_events and is the server-side filter for which events come back. A run watching its own run_id is using that subscription as its inbox.
• app/src/ai/agent_sdk/driver.rs — drives Oz conversations headlessly via the Warp CLI (locally for start_agent with execution_mode: local + Oz harness, and on cloud workers for cloud Oz runs). The same OrchestrationEventStreamer singleton is registered here (lib.rs:1564-1566 is unconditional aside from the OrchestrationV2 feature flag), so the streamer must serve a CLI/cloud process where there are no AgentViewController registrations at all.

Proposed changes

Consumer abstraction

The streamer's job is to deliver events to a consumer. Today there is one implicit consumer (the agent view), but in CLI and cloud worker processes the consumer is the agent_sdk::driver itself, which has no agent view. Generalize this: the streamer owns a set of registered consumers per conversation, where a consumer is anything that needs orchestration events delivered for that conversation.

The registry lives inside OrchestrationEventStreamer as part of the per-conversation ConversationStreamState (a single streams: HashMap<AIConversationId, ConversationStreamState> map collects every per-conversation field — watched run_ids, cursor, pending message IDs, consumers, SSE connection, restore-retry counter — under one entry). Consumers are identified by EntityId (the terminal pane id for an agent view; the driver model id for agent_sdk). Two public methods drive the registry:

• register_consumer(conversation_id, consumer_id, ctx) — inserts and re-evaluates eligibility through reevaluate_eligibility, which calls start_sse_connection if the conversation is newly eligible.
• unregister_consumer(conversation_id, consumer_id, ctx) — removes and re-evaluates eligibility, tearing down the SSE if the conversation is no longer eligible.

This avoids introducing a separate singleton and the event-subscribe plumbing that would come with it. The streamer is the only consumer of these signals, so co-locating the state keeps the lifecycle decisions in one place.

Two callers wire up registrations through the free helpers register_agent_event_consumer / unregister_agent_event_consumer:

• The agent view path: ActiveAgentViewsModel reacts to EnteredAgentView / ExitedAgentView and calls the helpers on behalf of the open view.
• The driver path: agent_sdk::driver calls the same helpers around its run lifetime.

The streamer's eligibility check observes a single signal — has_active_consumer(conversation_id) reads the conversation's stream entry — and does not care which type registered. In the GUI client this collapses to "agent view is open somewhere"; in CLI/cloud workers it collapses to "the driver is running."

A single EntityId per consumer is enough: the streamer treats every consumer as opaque, the entity id is unique per pane / driver model, and unregister keys back to that same id.

Eligibility predicate

The streamer treats parent and child agent runs differently because the trigger conditions are different, but both check the same consumer signal.

Child role — the conversation has a parent agent run from this process's perspective. Two signals satisfy this: parent_conversation_id.is_some() (the parent has a local placeholder, set by start_new_child_conversation when the GUI parent spawned the child) OR parent_agent_id.is_some() (the conversation knows its parent's server-side agent identifier, which under v2 is the parent's run_id). The two signals address two different processes:

• The parent's GUI process gets parent_conversation_id set when it creates the child placeholder via start_new_child_conversation.
• The driver-hosted process (CLI subprocess for execution_mode: local, cloud worker for cloud children) never sees the parent's local AIConversationId. It does fetch the parent's run_id from the server task metadata (get_ambient_agent_task returns parent_run_id), so the agent_sdk driver stamps that run_id onto the conversation's parent_agent_id field at register time. That stamp is what the streamer's child-role check picks up.

The subscription is the child's inbox. It is gated on having an active consumer in this process the same way the parent role is. In the process where the child run actually lives, the agent_sdk driver registers a consumer for the run's lifetime, so the child's inbox stays live for the whole run. In any other process (e.g. the user's GUI tracking a cloud child), the child's own SSE only opens while a consumer is registered — i.e. the child's agent view is open. Without a local consumer the events would have nowhere to land, and the user's GUI already sees child→parent traffic via the parent's SSE. This applies to every harness — Oz, ClaudeCode, Gemini, headless CLI children spawned via start_agent with execution_mode: local, and cloud children. Children today cannot themselves spawn children; if that constraint is lifted later, this role keeps applying unchanged.

Parent role — the conversation has at least one child run_id registered in watched_run_ids (from register_watched_run_id in start_agent.rs). The subscription delivers child lifecycle and child→parent messages into the parent's consumer. The parent role is gated on having an active consumer. In the GUI that means the agent view is open; in CLI/cloud it means the agent driver is running. When the last consumer for a parent disappears, child events for that parent are stored on the server and backfilled via the cursor when a consumer comes back.

Today, child agent runs cannot themselves spawn children, so no live conversation simultaneously holds both roles. The design must still admit the case so that allowing children-of-children later is a code change to the spawn path, not to the subscription model. Both roles' run_id contributions are unioned into the SSE filter whenever both apply.

The stronger present-day motivator for the consumer abstraction is a different shape: a top-level cloud Oz agent run — not itself a child — that spawns children. It has the parent role only, runs on a cloud worker with no agent view, and is driven by the agent_sdk driver. Without the consumer abstraction the parent gate would never be satisfied (no agent view ever exists in that process) and the cloud Oz agent could not receive its children's events. With the abstraction the driver registers as the consumer and the parent role is eligible.

Solo conversations — neither parent nor child — are excluded. They have no role in the orchestration tree and no inbox traffic to receive.

Formally, a conversation should be subscribed iff:

has_active_consumer()
  AND (is_child_agent_conversation() OR has_at_least_one_watched_child_run_id())

Where has_active_consumer() returns true when at least one AgentViewController or agent_sdk::driver is registered for this conversation. This predicate is the single invariant the streamer maintains. Every code path either makes a conversation eligible (and ensures a connection exists) or makes it ineligible (and tears the connection down).

Subscription drivers

Children. The trigger is server-token assignment, not status. on_server_token_assigned calls ensure_self_run_id_watched to register the self run_id and re-runs reevaluate_eligibility immediately. Children must be listening as soon as they have a run_id, regardless of status. Teardown for children happens only on RemoveConversation / DeletedConversation.

Parents. Subscribe to a single "consumer changed" signal from the registry described above:

• On consumer-removed for a conversation: reevaluate_eligibility runs the predicate and tears the SSE down if the conversation is no longer eligible. If it is also a child, the child role keeps it alive.
• On consumer-added for a conversation: reevaluate_eligibility opens the SSE if newly eligible. This handles both the GUI reopen case (agent view opened after being closed) and the CLI startup case (driver registered before any agent view exists).
• register_watched_run_id (called from start_agent.rs) re-evaluates eligibility after the insert. If a consumer exists, this opens or reconnects the SSE; if none exists, it is a no-op until a consumer registers.

reevaluate_eligibility is the single dispatch point: it computes the eligibility predicate and either calls start_sse_connection, reconnects, or tears down. Status is not part of the lifecycle decision for either role.

The agent_sdk driver registers itself as a consumer at the start of its run (a natural place is AgentDriver::execute_run for Oz, or where the third-party harness path picks up the task_id for ThirdParty harnesses) and unregisters when the run terminates. Registration is by AIConversationId so it composes with the existing per-conversation streamer state.

Because both roles share a single SSE connection per conversation, the SSE's run_ids filter must be the union of {self_run_id} (child role) and the registered child run_ids (parent role), where each role's contribution is included only when that role's eligibility is met. The simplest implementation is to compute the run_id list at SSE-open time from current state.

Trigger ordering and re-evaluation

Eligibility depends on three pieces of state, each of which lands at a different time and is set by a different code path:

• Conversation::has_parent_agent() — true when the conversation has either parent_conversation_id (set on a child created with a local placeholder) or parent_agent_id (the parent's run_id, stamped by the agent_sdk driver in driver-hosted processes). Available before any run_id is assigned for the local-placeholder case; depends on the parent's run_id for the driver case.
• self_run_id — set on ConversationServerTokenAssigned for this conversation.
• Watched child run_ids on a parent — added by register_watched_run_id only after the child receives its server token (start_agent.rs waits for ConversationServerTokenAssigned on the child, then registers under the parent).

A consumer that registers earlier than any of these will not yet make the conversation eligible. That is fine: re-evaluation happens at every state change, so the SSE opens at the moment eligibility flips, regardless of which event arrived first. Concretely, the streamer re-runs the predicate at exactly four sites:

1. register_consumer and unregister_consumer — consumer set changed.
2. register_watched_run_id — a child run_id was added to a parent's set.
3. on_server_token_assigned — this conversation received its run_id (and may now be a child).
4. on_conversation_removed for any other conversation — if it was a child of this one, its run_id was just pruned from this parent's watched set; the parent may have no remaining children.

A consumer never needs to re-register on its own to chase the run_id. It registers once at the start of its lifetime and unregisters once at the end; the streamer is responsible for catching up state changes in between.

A practical consequence for the GUI: opening an agent view for a brand-new conversation calls register_consumer immediately, but no SSE opens until either the conversation receives ConversationServerTokenAssigned (and is found to be a child) or register_watched_run_id runs against it (when its first child is spawned). For the CLI/cloud driver path the same applies: the driver registers immediately at run start, but the SSE waits until the run_id is assigned.

Solo exclusion at registration time

on_server_token_assigned calls ensure_self_run_id_watched, which inserts the conversation's own run_id only when the conversation already has a role: it has a parent (Conversation::has_parent_agent()) or it is already a parent (some other watched run_id is registered). Conversations that are not yet children at server-token time may later become parents via register_watched_run_id; that path runs ensure_self_run_id_watched again to add the self run_id once the parent role kicks in, so solo conversations stay out of the watched set entirely until and unless they enter the orchestration tree.

This avoids opening inbox subscriptions for conversations that have no orchestration role.

Removal of stale child run_ids in a still-eligible parent

In the existing RemoveConversation / DeletedConversation arm, also walk every other entry in watched_run_ids and remove the closed conversation's run_id from each set. Capture the run_id from BlocklistAIHistoryModel::conversation(conversation_id).and_then(|c| c.run_id()) before the conversation is removed (the event handler runs before history-model state is fully gone for RemoveConversation; for DeletedConversation we need the same guarantee — verify during implementation, fall back to passing the run_id on the event if necessary).

After the prune, re-evaluate the parent's eligibility:

• If the parent has remaining children and its view is still open, reconnect the SSE with the smaller run_id set.
• If the parent has no remaining children and is not itself a child, tear down its SSE.
• If the parent has no remaining children but is itself a child, keep the SSE alive for the child-role inbox.

Reconnect behavior

reconnect_sse runs the full is_eligible predicate before re-opening: if the conversation is no longer eligible, the connection is dropped without re-opening. The proactive reconnect (AgentEventDriverConfig::proactive_reconnect_after, ~14 minutes) and error-driven reconnect both pass through this gate, so an ineligible conversation stops reconnecting automatically.

State machine

Replace "agent view open" with "has active consumer" in the parent gate; otherwise the same shape:

stateDiagram-v2
    [*] --> Solo: conversation created
    Solo --> ChildOnly: server token assigned and parent_conversation_id set
    Solo --> ParentOnly: child run_id registered while consumer active
    Solo --> ParentLatent: child run_id registered while no consumer
    ChildOnly --> ChildAndParent: registers a grandchild
    ParentOnly --> ParentLatent: last consumer unregisters
    ParentLatent --> ParentOnly: consumer registers
    ChildOnly --> Subscribed: SSE active (always-on inbox)
    ParentOnly --> Subscribed: SSE active (consumer present)
    ChildAndParent --> Subscribed: SSE active (both roles)
    Subscribed --> ChildOnly: parent role ends (no children + no consumer)
    Subscribed --> ParentOnly: child role ends (rare; only via removal)
    Subscribed --> [*]: conversation removed
    ChildOnly --> [*]: conversation removed
    ParentOnly --> [*]: conversation removed
    ParentLatent --> [*]: conversation removed
    Solo --> [*]: conversation removed

A conversation is in Subscribed iff its entry in streams has sse_connection.is_some(). Exiting Subscribed always tears down the SSE.

Testing and validation

Add unit tests in orchestration_event_streamer_tests.rs covering the new invariants:

1. Solo conversation does not subscribe. Server token assigned for a conversation that is not a child and never spawns one; consumers come and go; status reaches Success → no entry in sse_connections at any point.
2. Child subscribes immediately on server-token assignment regardless of consumer state. A child conversation (parent_conversation_id set) gets server token while no consumer is registered → SSE is active. Adding/removing consumers does not affect the connection.
3. Headless CLI child of any harness subscribes. Cover Oz, ClaudeCode, and Gemini harness children spawned with execution_mode: local — each must have a live SSE once their run_id is assigned, with no agent view ever opened. The Oz CLI case must also have the agent_sdk driver registered as a consumer.
4. Parent subscribes when first child is registered while a consumer is active. Register a consumer first, then register_watched_run_id → connection opens.
5. Parent latent until a consumer registers. Children registered while no consumer exists → no connection. Consumer registers → connection opens with the right run_id list.
6. Last consumer leaving tears down (parent-only conversation). A subscribed parent that is not itself a child has its only consumer unregister; sse_connections/cursor/timer state are all gone. watched_run_ids is preserved so the parent can re-subscribe when a new consumer appears.
7. Last consumer leaving does not tear down a parent-and-child conversation. Forward-looking, since children cannot spawn children today; exercise the predicate by constructing a Conversation test fixture with both parent_conversation_id set and at least one watched child run_id. Verify it stays subscribed when its consumers leave (child role keeps it alive), and that the parent contribution is only present in the run_id filter while a consumer exists.
8. Reconnect on consumer return. Parent-only: last consumer leaves → consumer rejoins → new SSE connection opened with the latest cursor and the current set of child run_ids.
9. Stale child run_id is pruned. Parent with two children registered, one child conversation deleted → parent's watched_run_ids shrinks, SSE reconnects with the smaller set.
10. Last child removed leaves a non-child parent with no role → teardown. Parent that was never a child has its only child removed → connection torn down even if a consumer is still registered.
11. Multiple consumers do not double-tear-down. Two consumers (e.g. agent view + driver, or two agent views) for the same parent; one unregisters → SSE persists; second unregisters → SSE torn down.
12. Cloud Oz parent (driver-only consumer) receives child events. A top-level cloud Oz conversation (not itself a child) that spawns one or more children, with only the agent_sdk driver registered as a consumer (no agent view), must have all the child run_ids in the SSE filter — verifies that the consumer abstraction admits the driver to satisfy the parent gate. This is the present-day motivator for the abstraction.

Manual validation:

Observation setup. Each test below names the process where SSE state should appear: either the user's GUI Warp app (a desktop binary) or a driver process (a local CLI subagent subprocess, or a cloud Oz worker). The relevant log lines are the same in either process; the difference is which log file you tail.

Log lines to watch for, all at info level unless noted:

• register_consumer for {conv:?}: {consumer_id:?} (total=N) — a consumer registered.
• unregister_consumer for {conv:?}: {consumer_id:?} (remaining=N) — a consumer unregistered.
• Opening SSE stream for {conv:?} (gen=, run_ids=, since=) — SSE connection opened.
• SSE driver exited for {conv:?} (gen=) — SSE driver task exited (warn level).
• Tearing down SSE for {conv:?} (no longer eligible) — explicit teardown after eligibility flipped to false.

Where to tail:

• GUI process: the Warp app log for the active build flavor (e.g. ~/Library/Logs/dev.warp.Warp-Stable/warp.log on macOS).
• Local CLI driver subprocess: the subprocess's stderr or its dedicated log file. start_agent with execution_mode: local runs warp_cli as a subprocess; tail wherever that subprocess writes logs.
• Cloud Oz worker: the worker logs surfaced by the Oz UI / cloud logging tool for the run.
• Server-side: stream_agent_events requests in the dev warp-server access log — one request per active SSE; new requests on reconnect; disconnects when the client closes the stream.

A. Solo conversation

Start a regular cloud conversation. Don't call start_agent. Open and close its pane.

• GUI: register_consumer and unregister_consumer for the conversation, but no Opening SSE stream line at any point.
• Server: no stream_agent_events request.

B. Local parent + Local child (both in user's GUI; child runs as a local CLI subagent subprocess)

In the user's GUI, spawn a child via start_agent with execution_mode: local + a CLI harness (e.g. claude-code). The parent's conversation lives in the GUI; the child's run is hosted in a separate driver subprocess.

GUI process expectations:

• With parent's pane open and a child registered: register_consumer (AgentView) for parent, then Opening SSE stream for parent with run_ids = [child_run_id, parent_self_run_id] — the child run_id for child lifecycle events and the parent's self_run_id for child→parent messages.
• Child's Opening SSE stream does not appear in the GUI unless the user explicitly opens the child's view.
• Closing parent's pane: unregister_consumer for parent, then SSE driver exited for parent.

Local CLI driver subprocess expectations:

• At driver startup (after the run_id is assigned via streaming events): register_consumer (Driver) for child, then Opening SSE stream for child with run_ids containing the child's self_run_id.
• When the driver run completes: unregister_consumer (Driver) for child, then Tearing down SSE.

Server: one stream_agent_events request per active SSE.

C. Local parent + Cloud child (parent in GUI, child in cloud worker)

In the user's GUI, spawn a child via start_agent with cloud Oz harness. Parent runs in GUI; child runs on a cloud worker.

GUI process expectations:

• Parent: same as B — SSE only while parent's pane is open and the child run_id is registered. run_ids = [child_run_id, parent_self_run_id].
• Child: no Opening SSE stream for the child in the GUI unless the user opens the child's view (e.g. via the cloud agent transcript). The intentional behavior is that child→parent traffic flows through the parent's SSE; the child's own SSE in the GUI would be redundant.

Cloud worker expectations:

• register_consumer (Driver) for child on run start, then Opening SSE stream for child once run_id is assigned.
• When the run completes: unregister_consumer + Tearing down SSE.

D. Cloud parent + Local child (both in same cloud worker process)

A top-level cloud Oz parent driver spawns a CLI subagent locally (in the same worker process). Both runs are headless on the cloud worker — driver runs do not have a GUI; any user-side viewer pane on the parent or child is a passive remote-run view and is covered by section F. Two AgentDriver instances register two Driver consumers with the worker's single streamer.

Cloud worker expectations:

• Parent: register_consumer (Driver) for parent on run start. Once the parent registers a child run_id (from start_agent), Opening SSE stream for parent with run_ids = [child_run_id, parent_self_run_id] — the child run_id for child lifecycle and the parent's self_run_id for child→parent messages.
• Child: register_consumer (Driver) for child, then Opening SSE stream for child with run_ids = [child_self_run_id].
• Parent and child each unregister and tear down their own SSE when their respective drivers complete.

E. Cloud parent + Cloud child (separate cloud workers)

Like D but split across two worker processes. The parent worker holds the parent's SSE (with run_ids = [child_run_id, parent_self_run_id]); the child worker holds the child's SSE (run_ids = [child_self_run_id]). Each driver consumer is in its own process. Both runs are headless; any user-side viewer pane is covered by section F.

F. Passive view of a remote run

A conversation in the local process that is a passive view of an agent run hosted in another process. Two flavors share the same predicate path:

• Shared-session viewer. Open a pane that views someone else's shared session. The local conversation has is_viewing_shared_session() == true.
• Remote-child placeholder. Spawn a child via start_agent with execution_mode: cloud (e.g. cloud Oz). The user's GUI auto-opens a viewer pane for the child; the local placeholder conversation has is_remote_child() == true and parent_conversation_id set, but the actual run lives on the cloud worker.

In both cases the local process has no run to host — the inbox lives elsewhere — so opening an SSE here would re-inject events the real consumer has already processed.

• GUI: register_consumer (AgentView) when the pane opens, but no Opening SSE stream for the viewer's conversation_id at any point. The is_remote_run_view guard in is_eligible covers both flavors and prevents subscription even when the conversation has parent_conversation_id set or appears to have a watched run_id (the auto-opened cloud-child viewer satisfies both).
• Server: no stream_agent_events request from this client for the viewer's conversation_id. The parent's SSE in the same process is unaffected and continues to deliver child events for the cloud child via the parent's watched_run_ids.

Specific behaviors to spot-check after running B or C

1. Stale child run_id pruned. Spawn two children, then delete the second child's conversation. Expected in the parent's process (GUI for B/C, worker for D/E): a new Opening SSE stream for the parent with run_ids shrunk by one (and a generation bump). Server: previous parent stream_agent_events request disconnects, new one opens with the smaller run_id list.
2. Last child removed leaves a non-child parent with no role. Continuing from (1), delete the remaining child too. Expected: Tearing down SSE for the parent; no new Opening SSE stream follows.
3. Reopen parent — SSE re-establishes with cursor. Close the parent's pane in the GUI, then reopen. Expected: register_consumer followed by Opening SSE stream with since=<cursor> matching the last persisted cursor.
4. Solo with consumer registered. Open an agent view for a conversation that has no children registered and is not itself a child. Expected: register_consumer, but no Opening SSE stream for that conversation.

Run ./script/presubmit before opening the PR. Add a CHANGELOG-IMPROVEMENT: line for "Tighten orchestration event subscription scope: solo conversations no longer subscribe; parent subscriptions are tied to agent view openness; child subscriptions remain active for the lifetime of the run."

Risks and mitigations

• Race between server token assignment and consumer registration. Re-deriving eligibility from current state on every consumer-add and on every register_watched_run_id call covers the ordering. Verify with unit tests.
• Headless child without UI must still subscribe. A regression here breaks message delivery to CLI subagents. Tests (3) and the manual CLI-child step are the primary safeguards. The implementation must not gate the child path on consumer presence — only the parent path is consumer-gated.
• Driver lifecycle in the agent_sdk. The driver must register and unregister at the right boundaries: register before any child can be spawned and unregister only after the run has terminated and any teardown work is complete. Registering too late means the driver misses early grandchild events; unregistering too early causes the same. Pin the registration to the run's outer scope in AgentDriver::execute_run.
• Single SSE serves dual roles. A conversation that is both child and parent uses one connection with a unioned run_id set. Reconnects must include both contributions; the run_id list should be recomputed each time the connection is opened or reconnected. Add an assertion to surface a divergence in tests.
• Event ordering. Consumer-removed and RemoveConversation may arrive in either order. Both paths run idempotent teardown — verify by making the teardown helper safe to call when the conversation is already gone.

Follow-ups

• Expose a debug snapshot from the streamer (count of streams with an open sse_connection, count of streams with non-empty watched_run_ids, total run_ids across all sets, count of registered consumers per conversation, role classification per conversation) so we can monitor connection scope in production via a dev panel or telemetry.