Merge pull request #18 from nikomatsakis/main

refactor conductor API for "lazy initialization", fix race condition

Author: nikomatsakis

md/architecture.md

@@ -46,6 +46,8 @@ The conductor uses `_proxy/successor/request` bidirectionally with different mea
 - **Proxy → Conductor**: Proxy sends `_proxy/successor/request` to send a message TO its successor (downstream)
 - **Conductor → Proxy**: Conductor sends `_proxy/successor/request` to deliver a message FROM the successor (upstream)
 
+**Important**: The conductor maintains message ordering by routing all forwarding decisions through a central event loop, preventing responses from overtaking notifications even though they use different transport paths.
+
 **Downstream flow (Proxy 1 sending to Proxy 2):**
 1. Conductor sends normal ACP request to Proxy 1
 2. Proxy 1 sends `_proxy/successor/request` to conductor (meaning "send this TO my successor")
@@ -68,8 +70,9 @@ The **conductor** is the orchestrator that manages the proxy chain. From the edi
 
 **Responsibilities:**
 1. **Process Management**: Spawns and manages component processes
-2. **Message Routing**: Routes messages through the proxy chain
+2. **Message Routing**: Routes messages through the proxy chain, preserving send order
 3. **Capability Adaptation**: Bridges between different component capabilities
+4. **Message Ordering**: Ensures all messages maintain send order when forwarded through proxy chains
 
 **Usage:**
 ```bash

md/conductor.md

@@ -58,6 +58,8 @@ conductor mcp 54321
 
 The conductor routes ALL messages between components. No component talks directly to another.
 
+**Message ordering**: The conductor preserves message send order by routing all forwarding decisions through a central event loop, preventing responses from overtaking notifications.
+
 **Message flow types:**
 
 1. **Editor → First Component**: Conductor forwards normal ACP messages
@@ -200,6 +202,31 @@ The conductor uses an actor-based architecture with message passing via channels
 - **Message router**: Central actor that receives `ConductorMessage` enums and routes appropriately
 - **MCP bridge actors**: Manage MCP-over-ACP connections
 
+### Message Ordering Invariant
+
+**Critical invariant**: All messages (requests, responses, notifications) between any two endpoints must maintain their send order.
+
+The conductor ensures this invariant by routing **all** message forwarding through its central message queue (`ConductorMessage` channel). This prevents faster message types (responses) from overtaking slower ones (notifications).
+
+#### Why This Matters
+
+Without ordering preservation, a race condition can occur:
+1. Agent sends `session/update` notification
+2. Agent responds to `session/prompt` request  
+3. Response takes a fast path (reply_actor with oneshot channels)
+4. Notification takes slower path (handler pipeline)
+5. **Response arrives before notification** → client loses notification data
+
+#### Implementation
+
+The conductor uses extension traits to route all forwarding through the central queue:
+
+- `JrConnectionCxExt::send_proxied_message_via` - Routes both requests and notifications
+- `JrRequestCxExt::respond_via` - Routes responses through the queue
+- `JrResponseExt::forward_response_via` - Ensures response forwarding maintains order
+
+All message forwarding in both directions (client-to-agent and agent-to-client) flows through the conductor's central event loop, which processes `ConductorMessage` enums sequentially. This serialization ensures messages arrive in the same order they were sent.
+
 ### Message Routing Implementation
 
 The conductor uses a recursive spawning pattern:

md/transport-architecture.md

@@ -154,6 +154,14 @@ Incoming Protocol Actor
 Handler or Reply Actor
 ```
 
+### Message Ordering in the Conductor
+
+When the conductor forwards messages between components, it must preserve send order to prevent race conditions. The conductor achieves this by routing all message forwarding through a central message queue.
+
+**Key insight**: While the transport actors operate independently, the **conductor's routing logic** serializes all forwarding decisions through a central event loop. This ensures that even though responses use a "fast path" (reply_actor with oneshot channels) at the transport level, the decision to forward them is serialized with notification forwarding at the protocol level.
+
+Without this serialization, responses could overtake notifications when both are forwarded through proxy chains, causing the client to receive messages out of order. See [Conductor Implementation](./conductor.md#message-ordering-invariant) for details.
+
 ## Transport Trait
 
 The `IntoJrConnectionTransport` trait defines how to bridge internal channels with I/O: