Skip to main content

muse_code_sdk/
session.rs

1//! Session verbs and turn submission.
2
3mod approval_route;
4mod fold_view;
5mod gap_route;
6mod notification_params;
7mod reconnect;
8mod state;
9mod submit;
10mod turn_route;
11mod user_input;
12
13use std::collections::HashMap;
14use std::future::Future;
15use std::sync::{Arc, Mutex, Weak};
16
17use serde_json::Value;
18
19use crate::approval::ApprovalDecisionInput;
20use crate::client::{ClientShared, lock};
21use crate::fold::SessionFold;
22use crate::msp::{
23    ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, HistoryMode, Item,
24    ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, Notification,
25    PendingRequestKind, SessionHistory, SessionResumeResult, SessionStartResult,
26    TurnCompletedParams, TurnStartedParams, TurnUnqueuedParams,
27};
28use crate::turn::TurnWaitError;
29
30use approval_route::ApprovalRoute;
31pub use fold_view::SessionFoldView;
32pub(crate) use fold_view::{drop_unreadable_snapshot, resume_history_items};
33use gap_route::GapRoute;
34use notification_params::{approval_id, decode, turn_id};
35use state::{PendingCommandGuard, SessionState};
36
37pub use reconnect::{PendingTurn, ReconnectResolution, Reconnected};
38pub use submit::SendUserTurnOptions;
39
40const MAX_SETTLED_TURN_ALIASES: usize = 128;
41pub(crate) const MAX_RETIRED_TURNS: usize = 256;
42pub(crate) const MAX_ACTIVE_TURNS: usize = 128;
43
44/// The server's result that opened a session, as typed by this SDK.
45#[derive(Clone, Debug, PartialEq)]
46#[non_exhaustive]
47pub enum SessionOpening {
48    /// The `session/start` result.
49    Start(Box<SessionStartResult>),
50    /// The `session/resume` result: the history it served and the turn the
51    /// host still runs, if any.
52    Resume(Box<SessionResumeResult>),
53}
54
55/// One server session on a client: it submits turns, answers approvals and
56/// questions, and keeps a fold of the events it applied. Clones share it.
57#[derive(Clone)]
58pub struct Session {
59    inner: Arc<SessionInner>,
60}
61
62/// The items a resume served: `history.items` when inline, else the
63/// snapshot's `state.items` (`snapshot` and `anchoredSnapshot` modes). An
64/// unknown mode serves none: its reading is "page it yourself".
65fn served_history_items(history: &SessionHistory) -> Option<&[Item]> {
66    if matches!(history.mode, HistoryMode::Unknown(_)) {
67        return None;
68    }
69    history.items.as_deref().or_else(|| {
70        history
71            .snapshot
72            .as_ref()
73            .map(|snapshot| snapshot.state.items.as_slice())
74    })
75}
76
77impl Session {
78    pub(crate) fn from_opening(
79        client: Arc<ClientShared>,
80        opening: SessionOpening,
81        history: &[Value],
82        dropped_snapshot_schema_version: Option<u64>,
83    ) -> Self {
84        let session_id = match &opening {
85            SessionOpening::Start(result) => result.session.session_id.clone(),
86            SessionOpening::Resume(result) => result.session.session_id.clone(),
87        };
88        let (approval, pending_approvals) = ApprovalRoute::new();
89        let gaps = GapRoute::new(&session_id);
90        let fold = fold_view::seeded_fold(&session_id, history);
91        let inner = Arc::new(SessionInner {
92            client,
93            session_id,
94            opening,
95            fold: Mutex::new(fold),
96            state: Arc::new(Mutex::new(SessionState::default())),
97            approval,
98            gaps,
99            dropped_snapshot_schema_version,
100        });
101        if let SessionOpening::Resume(result) = &inner.opening {
102            let mut state = lock(&inner.state);
103            // A resend's answer may name a turn that settles before the first
104            // `resolve_reconnect`; keep it claimable until such a call, past its
105            // refusals, ends.
106            state.hold_settled_aliases = true;
107            state.last_turn_id = result.last_turn.as_ref().map(|last| last.turn_id.clone());
108        }
109        inner
110            .approval
111            .spawn(inner.runtime(), Arc::downgrade(&inner), pending_approvals);
112        if let SessionOpening::Resume(result) = &inner.opening
113            && let Some(items) = served_history_items(&result.history)
114        {
115            // History reaches a turn when its route opens: now for the turn the
116            // host still runs, later for a finished turn once a live event (the
117            // reconciliation terminal) or a claim opens its route.
118            // Opening no route for the rest keeps MAX_ACTIVE_TURNS slots free;
119            // finished turns stay readable through `opening()`.
120            let mut history_turn_items: HashMap<String, Vec<usize>> = HashMap::new();
121            for (index, item) in items.iter().enumerate() {
122                if let Some(turn_id) = &item.turn_id {
123                    history_turn_items
124                        .entry(turn_id.clone())
125                        .or_default()
126                        .push(index);
127                }
128            }
129            lock(&inner.state).history_turn_items = history_turn_items;
130            // A turn `lastTurn` restates has ended, even if the host still
131            // reports it running: its terminal is final. It opens no route,
132            // so it holds no slot.
133            if let Some(active_turn_id) = result.session.active_turn_id.as_deref()
134                && inner.restated_last_turn(active_turn_id).is_none()
135            {
136                inner.turn_handle(active_turn_id);
137            }
138        }
139        Self { inner }
140    }
141
142    /// The session id the server returned: the one the start or resume named,
143    /// or one the server minted.
144    pub fn session_id(&self) -> &str {
145        self.inner.session_id()
146    }
147
148    /// The result that opened this session. For a resume, `history.mode` can
149    /// name a snapshot mode while `history.snapshot` is `None`: the SDK
150    /// dropped a snapshot newer than it understands (see
151    /// [`Session::dropped_snapshot_schema_version`]).
152    pub fn opening(&self) -> &SessionOpening {
153        &self.inner.opening
154    }
155
156    /// The `schemaVersion` of a resume snapshot this SDK dropped because it is
157    /// newer than the session view this SDK understands, if it dropped one.
158    /// The resume then used none of the snapshot's state, for the fold or the
159    /// turns, and the opening's `history.snapshot` is `None`. Events after the
160    /// snapshot's cursor still stream and apply, so the fold holds only what
161    /// came after it. To get the earlier history, upgrade
162    /// muse-code-sdk, or close this client and resume the session on a new one
163    /// asking for inline history (`ResumeSessionOptions::history`), which the
164    /// host serves when it fits its budget. Resuming the same session again on
165    /// this client is no remedy: the newer session's fold stops.
166    pub fn dropped_snapshot_schema_version(&self) -> Option<u64> {
167        self.inner.dropped_snapshot_schema_version
168    }
169
170    /// True once the transport ended on a client that is not durable (an
171    /// ephemeral host, or a durability value this SDK does not know): the SDK
172    /// assumes nothing survives to resume, so its fallible verbs refuse with
173    /// [`MuseError::SessionDiscarded`](crate::errors::MuseError::SessionDiscarded).
174    pub fn is_discarded(&self) -> bool {
175        lock(&self.inner.state).discarded
176    }
177
178    /// Fixes the routing of approvals the resume result lists as pending.
179    pub(crate) fn fix_resume_approval_routing(&self) {
180        if let SessionOpening::Resume(result) = &self.inner.opening {
181            self.inner.approval.fix_handoff_routing(
182                result
183                    .pending_requests
184                    .iter()
185                    .filter(|pointer| pointer.kind == PendingRequestKind::Approval)
186                    .filter_map(|pointer| pointer.approval_id.clone()),
187            );
188        }
189    }
190
191    /// Replaces the approval handler for this session.
192    ///
193    /// A request for a turn this session has already settled gets the offered
194    /// rejecting choice without reaching the handler, and an answer whose turn
195    /// settles while the handler decides is replaced the same way; with no
196    /// rejecting choice offered, nothing is sent, and a later stage that offers
197    /// one gets it. A [`Turn`](crate::turn::Turn) that
198    /// [`Session::send_user_turn`] or [`Session::resolve_reconnect`] returned
199    /// already failed, because the session was already tracking as many active
200    /// turns as it can, counts as settled until a later call returns a live turn
201    /// for it. Approvals for a turn this `Session` no longer remembers as
202    /// settled (it keeps only its most recent settled turns, and a resumed
203    /// `Session` starts with none) still reach the handler as usual.
204    pub fn on_approval<Handler, HandlerFuture>(&self, handler: Handler)
205    where
206        Handler: Fn(ApprovalRequestParams) -> HandlerFuture + Send + Sync + 'static,
207        HandlerFuture: Future<Output = ApprovalDecisionInput> + Send + 'static,
208    {
209        self.inner.approval.on_approval(handler);
210    }
211
212    pub(crate) fn downgrade(&self) -> Weak<SessionInner> {
213        Arc::downgrade(&self.inner)
214    }
215}
216
217pub(crate) struct SessionInner {
218    client: Arc<ClientShared>,
219    session_id: String,
220    opening: SessionOpening,
221    fold: Mutex<SessionFold>,
222    state: Arc<Mutex<SessionState>>,
223    approval: ApprovalRoute,
224    gaps: GapRoute,
225    dropped_snapshot_schema_version: Option<u64>,
226}
227
228impl SessionInner {
229    pub(crate) fn session_id(&self) -> &str {
230        &self.session_id
231    }
232
233    /// The runtime that built the client: this session's background tasks
234    /// run there, whichever runtime opened the session.
235    pub(super) fn runtime(&self) -> &tokio::runtime::Handle {
236        &self.client.runtime
237    }
238
239    /// Every live notification enters through the gap route: a
240    /// `view/gap` starts the splice-fill, a frame behind a pending hole is
241    /// held, a served twin is refused once, and everything else applies now.
242    pub(crate) fn apply(self: &Arc<Self>, notification: Notification) {
243        self.gaps.route(self, notification);
244    }
245
246    fn apply_now(self: &Arc<Self>, notification: Notification) {
247        self.fold_event(&notification);
248        self.route_now(notification);
249    }
250
251    /// Hands one notification to the turn and item routes, without folding it.
252    fn route_now(self: &Arc<Self>, notification: Notification) {
253        let Notification { method, params, .. } = notification;
254        match method.as_str() {
255            "item/started" => {
256                let _ = decode::<ItemStartedParams>(&method, params)
257                    .map(|params| self.push_item(params.item));
258            }
259            "item/updated" => {
260                let _ = decode::<ItemUpdatedParams>(&method, params)
261                    .map(|params| self.push_item(params.item));
262            }
263            "item/completed" => {
264                let _ = decode::<ItemCompletedParams>(&method, params)
265                    .map(|params| self.push_item(params.item));
266            }
267            "item/delta" => {
268                let _ = decode::<ItemDeltaParams>(&method, params)
269                    .map(|params| self.push_delta(params));
270            }
271            // The server-request form carries the same params.
272            "approval/requested" | "approval/request" => {
273                let turn_id = turn_id(&params);
274                let approval_id = approval_id(&params);
275                match decode::<ApprovalRequestParams>(&method, params) {
276                    Ok(params) => self.approval.enqueue_requested(self, params),
277                    Err(error) => {
278                        // Its other form must not reach a handler for a turn this
279                        // fails; a frame naming no turn fails nothing and is dropped.
280                        // The turn settles first, so no owed copy sees it unsettled.
281                        self.fail_named_turn(turn_id.clone(), error);
282                        if let (Some(turn_id), Some(approval_id)) =
283                            (turn_id.as_deref(), approval_id.as_deref())
284                        {
285                            self.approval.retire_owing(approval_id, turn_id, 0);
286                        }
287                    }
288                }
289            }
290            "approval/updated" => {
291                let approval_id = approval_id(&params);
292                match decode::<ApprovalUpdatedParams>(&method, params) {
293                    Ok(params) => self.approval.enqueue_updated(self, params),
294                    Err(error) => {
295                        let tracked = approval_id.as_deref().and_then(|approval_id| {
296                            Some((approval_id, self.approval.tracked_turn(approval_id)?))
297                        });
298                        let turn_id = tracked.as_ref().map(|(_, turn_id)| turn_id.clone());
299                        self.fail_named_turn(turn_id, error);
300                        if let Some((approval_id, _)) = tracked {
301                            self.approval.retire_tracked(approval_id);
302                        }
303                    }
304                }
305            }
306            "approval/resolved" => {
307                let approval_id = approval_id(&params);
308                match decode::<ApprovalResolvedParams>(&method, params) {
309                    Ok(params) => {
310                        self.approval.retire(&params.approval_id);
311                    }
312                    Err(_) => {
313                        if let Some(approval_id) = approval_id.as_deref() {
314                            self.approval.retire(approval_id);
315                        }
316                    }
317                }
318            }
319            "turn/started" => {
320                let turn_id = turn_id(&params);
321                match decode::<TurnStartedParams>(&method, params) {
322                    Ok(params) => self.mark_started(&params.turn_id),
323                    Err(error) => self.fail_named_turn(turn_id, error),
324                }
325            }
326            "turn/completed" => {
327                let turn_id = turn_id(&params);
328                match decode::<TurnCompletedParams>(&method, params) {
329                    Ok(params) => self.settle_turn(params),
330                    Err(error) => self.fail_named_turn(turn_id, error),
331                }
332            }
333            "turn/unqueued" => {
334                let turn_id = turn_id(&params);
335                match decode::<TurnUnqueuedParams>(&method, params) {
336                    Ok(params) => self.settle_unqueued(params),
337                    Err(error) => self.fail_named_turn(turn_id, error),
338                }
339            }
340            _ => {}
341        }
342    }
343
344    pub(crate) fn transport_ended(&self, discard: bool) {
345        self.approval.abort();
346        self.gaps.abort();
347        // After the walker abort, so the hole it was filling can never fill;
348        // before the settle, so a turn it wakes already reads the stop.
349        self.stop_fold_on_cut_fill();
350        let mut state = lock(&self.state);
351        state.settle_source_failure(TurnWaitError::SourceClosed);
352        if !discard {
353            return;
354        }
355        state.discarded = true;
356        state.last_turn_settled = None;
357        state.pending_commands.clear();
358        state.forget_submissions();
359        state.settled_turns.clear();
360        state.settled_turn_order.clear();
361        state.retired_turns.clear();
362        state.retired_turn_order.clear();
363        state.cap_refused_turns.clear();
364        state.cap_refused_turn_order.clear();
365    }
366
367    pub(crate) fn is_command_discarded(&self, command_id: &str) -> bool {
368        lock(&self.state).is_command_discarded(command_id)
369    }
370
371    pub(crate) fn fail_event_source(&self, failure: TurnWaitError) {
372        if matches!(failure, TurnWaitError::EventSourceFailed { .. }) {
373            self.mark_fold_lost();
374        }
375        self.approval.abort();
376        self.gaps.abort();
377        // After the walker abort and before the settle, as in `transport_ended`.
378        self.stop_fold_on_cut_fill();
379        lock(&self.state).settle_source_failure(failure);
380    }
381
382    /// The session's retained event-source failure, for the client's own
383    /// ordering tests.
384    #[cfg(test)]
385    pub(crate) fn event_source_failure(&self) -> Option<TurnWaitError> {
386        lock(&self.state).event_source_failure.clone()
387    }
388
389    /// Whether this session's client has begun `close()`. The approval route
390    /// reads it here, so it holds no client of its own.
391    fn client_closed(&self) -> bool {
392        self.client.is_closed()
393    }
394
395    pub(crate) fn begin_close(&self) -> Option<tokio::task::JoinHandle<()>> {
396        let worker = self.approval.detach();
397        // The slot is empty now, so this abort cannot reach the caller's worker.
398        self.fail_event_source(TurnWaitError::ClientClosed);
399        worker
400    }
401}
402
403#[cfg(test)]
404mod tests {
405    use std::collections::HashSet;
406    use std::future::Future;
407    use std::io;
408    use std::pin::Pin;
409    use std::task::{Context, Poll, Waker};
410
411    use tokio::sync::mpsc;
412
413    use super::state::TurnRoute;
414    use super::*;
415    use crate::DuplexTransport;
416    use crate::client::{MuseClient, ResumeSessionOptions, StartSessionOptions};
417    use crate::msp::SessionDurability;
418    use crate::turn::{TurnHandle, TurnOutcome};
419
420    struct ChannelTransport {
421        inbound: mpsc::UnboundedReceiver<String>,
422    }
423
424    impl DuplexTransport for ChannelTransport {
425        fn read_chunk(
426            &mut self,
427        ) -> Pin<Box<dyn Future<Output = io::Result<Option<String>>> + Send + '_>> {
428            Box::pin(async { Ok(self.inbound.recv().await) })
429        }
430
431        fn write(
432            &mut self,
433            _frame: &str,
434        ) -> Pin<Box<dyn Future<Output = io::Result<()>> + Send + '_>> {
435            Box::pin(async { Ok(()) })
436        }
437    }
438
439    /// Hands each scripted reply out only when its request is written,
440    /// re-keyed to that request's id (as the scripted test host does), so a
441    /// reply can never reach the driver before the request it answers is
442    /// pending. A request with no scripted reply gets none.
443    struct RepliesOnWrite {
444        inbound: mpsc::UnboundedReceiver<String>,
445        outbound: mpsc::UnboundedSender<String>,
446        replies: std::collections::VecDeque<(&'static str, serde_json::Value)>,
447    }
448
449    impl DuplexTransport for RepliesOnWrite {
450        fn read_chunk(
451            &mut self,
452        ) -> Pin<Box<dyn Future<Output = io::Result<Option<String>>> + Send + '_>> {
453            Box::pin(async { Ok(self.inbound.recv().await) })
454        }
455
456        fn write(
457            &mut self,
458            frame: &str,
459        ) -> Pin<Box<dyn Future<Output = io::Result<()>> + Send + '_>> {
460            if let Ok(request) = serde_json::from_str::<serde_json::Value>(frame.trim())
461                && self
462                    .replies
463                    .front()
464                    .is_some_and(|(method, _)| request["method"] == *method)
465                && let Some((_, mut reply)) = self.replies.pop_front()
466            {
467                reply["id"] = request["id"].clone();
468                let _ = self.outbound.send(format!("{reply}\n"));
469            }
470            Box::pin(async { Ok(()) })
471        }
472    }
473
474    fn poll_once<F: Future + ?Sized>(future: Pin<&mut F>) -> Poll<F::Output> {
475        future.poll(&mut Context::from_waker(Waker::noop()))
476    }
477
478    /// `close()` takes the calling handler's own worker
479    /// out of its slot, so a transport end while that handler waits in
480    /// `close()` cannot abort it. Without a host the handler's `close()` would
481    /// finish first, so the handler parks inside `close()` until released.
482    #[tokio::test(flavor = "current_thread")]
483    async fn transport_end_does_not_abort_a_handler_waiting_in_close() {
484        let (outbound, inbound) = mpsc::unbounded_channel();
485        let replies = std::collections::VecDeque::from([(
486            "session/start",
487            serde_json::json!({
488                "jsonrpc": "2.0",
489                "id": 0,
490                "result": {
491                    "session": {
492                        "sessionId": "session-1",
493                        "path": "/tmp/session-1.jsonl",
494                        "status": "idle",
495                        "activeTurnId": null,
496                        "createdAt": "2026-09-29T00:00:00Z",
497                        "updatedAt": "2026-09-29T00:00:00Z",
498                        "workspaceRoot": null,
499                        "providerId": null,
500                        "modelId": null,
501                        "turnCount": 0,
502                        "forkedFrom": null
503                    },
504                    "viewCursor": "cursor-1"
505                }
506            }),
507        )]);
508        let client = Arc::new(MuseClient::with_command_id_minter(
509            RepliesOnWrite {
510                inbound,
511                outbound,
512                replies,
513            },
514            SessionDurability::Durable,
515            || "command-1".to_owned(),
516        ));
517        let session = client.start_session(StartSessionOptions::default()).await;
518        assert!(session.is_ok(), "session opens");
519        let Ok(session) = session else {
520            return;
521        };
522
523        let (entered_tx, entered_rx) = tokio::sync::oneshot::channel::<()>();
524        let (release_tx, release_rx) = tokio::sync::oneshot::channel::<()>();
525        let (done_tx, done_rx) = tokio::sync::oneshot::channel::<()>();
526        let signals = Arc::new(Mutex::new(Some((entered_tx, release_rx, done_tx))));
527        let handler_client = Arc::clone(&client);
528        session.on_approval(move |_| {
529            let client = Arc::clone(&handler_client);
530            let signals = lock(&signals).take();
531            async move {
532                if let Some((entered_tx, release_rx, done_tx)) = signals {
533                    let mut close = Box::pin(client.close());
534                    let _ = poll_once(close.as_mut());
535                    let _ = entered_tx.send(());
536                    let _ = release_rx.await;
537                    let _ = done_tx.send(());
538                }
539                ApprovalDecisionInput {
540                    choice_id: "allow_once".to_owned(),
541                    feedback: None,
542                }
543            }
544        });
545        session.inner.apply(approval_requested("approval-1"));
546
547        // An aborted handler drops its senders, so each wait resolves either way.
548        assert!(entered_rx.await.is_ok(), "handler entered close()");
549        session.inner.transport_ended(false);
550        let _ = release_tx.send(());
551        assert!(
552            done_rx.await.is_ok(),
553            "transport end aborted the closing handler"
554        );
555    }
556
557    /// An approval for turn-1 that offers allow-once and an abort.
558    fn approval_requested(approval_id: &str) -> Notification {
559        Notification {
560            jsonrpc: crate::msp::JsonRpcVersion::V2,
561            method: "approval/requested".to_owned(),
562            params: serde_json::json!({
563                "sessionId": "session-1",
564                "approvalId": approval_id,
565                "turnId": "turn-1",
566                "taskId": "task-1",
567                "itemId": "item-1",
568                "toolCallId": "call-1",
569                "toolName": "shell",
570                "rawArgs": "{}",
571                "viewCursor": "cursor-2",
572                "sourceRange": {
573                    "stream": {"kind": "run", "id": "turn-1"},
574                    "first": {"id": "event-1", "sequence": 1},
575                    "last": {"id": "event-1", "sequence": 1}
576                },
577                "subject": {"kind": "shell", "command": "pwd"},
578                "currentRequirementId": {"approvalId": approval_id, "sourceIndex": 0},
579                "availableChoices": [
580                    {
581                        "choiceId": "allow_once",
582                        "label": "Allow once",
583                        "decision": "approved",
584                        "scope": "once"
585                    },
586                    {
587                        "choiceId": "abort",
588                        "label": "Abort",
589                        "decision": "abort",
590                        "scope": "once"
591                    }
592                ],
593                "protectedWrite": false,
594                "judgeEscalated": false
595            })
596            .as_object()
597            .cloned(),
598            emitted_at_ms: None,
599        }
600    }
601
602    /// Builds an `approval/requested` notification for one approval id.
603    type ApprovalFixture = fn(&str) -> Notification;
604
605    /// A handler runs on its session's approval worker. When it opens a newer
606    /// `Session` for its own id, registering that one fails the older session
607    /// from the handler's own task, and that failure aborts the older
608    /// session's approval worker, but not the one it runs on: the handler goes
609    /// on to finish instead of being cancelled at its next await.
610    #[tokio::test(flavor = "current_thread")]
611    async fn a_handler_that_opens_a_newer_session_for_its_own_id_is_not_cancelled() {
612        let (inbound, reads) = mpsc::unbounded_channel();
613        let client = Arc::new(MuseClient::with_command_id_minter(
614            ChannelTransport { inbound: reads },
615            SessionDurability::Durable,
616            || "command-1".to_owned(),
617        ));
618        assert!(inbound.send(opened_session(1, "session-1")).is_ok());
619        let session = client.start_session(StartSessionOptions::default()).await;
620        assert!(session.is_ok(), "the session opens");
621        let Ok(session) = session else {
622            return;
623        };
624
625        let (reopened_tx, reopened_rx) = tokio::sync::oneshot::channel::<bool>();
626        let (release_tx, release_rx) = tokio::sync::oneshot::channel::<()>();
627        let (done_tx, done_rx) = tokio::sync::oneshot::channel::<()>();
628        let signals = Arc::new(Mutex::new(Some((reopened_tx, release_rx, done_tx))));
629        let handler_client = Arc::clone(&client);
630        session.on_approval(move |_| {
631            let signals = lock(&signals).take();
632            let client = Arc::clone(&handler_client);
633            let host = inbound.clone();
634            async move {
635                if let Some((reopened_tx, release_rx, done_tx)) = signals {
636                    let _ = host.send(opened_session(2, "session-1"));
637                    let newer = client.start_session(StartSessionOptions::default()).await;
638                    let _ = reopened_tx.send(newer.is_ok());
639                    let _ = release_rx.await;
640                    let _ = done_tx.send(());
641                }
642                ApprovalDecisionInput {
643                    choice_id: "allow_once".to_owned(),
644                    feedback: None,
645                }
646            }
647        });
648        session.inner.apply(approval_requested("approval-1"));
649
650        // A cancelled handler drops its senders, so each wait resolves.
651        assert_eq!(
652            reopened_rx.await.ok(),
653            Some(true),
654            "the handler opened a newer session"
655        );
656        assert!(
657            session.inner.event_source_failure().is_some(),
658            "control: registering the newer session failed the older one"
659        );
660        let _ = release_tx.send(());
661        assert!(
662            done_rx.await.is_ok(),
663            "failing the older session aborted the worker its handler runs on"
664        );
665        client.close().await;
666    }
667
668    /// A handler can hold the session's last handle and drop it partway
669    /// through. The session's approval route is then dropped on the worker
670    /// the handler runs on, which it doesn't abort: the handler finishes.
671    #[tokio::test(flavor = "current_thread")]
672    async fn a_handler_that_drops_the_sessions_last_handle_mid_run_finishes() {
673        let (inbound, reads) = mpsc::unbounded_channel();
674        let client = MuseClient::with_command_id_minter(
675            ChannelTransport { inbound: reads },
676            SessionDurability::Durable,
677            || "command-1".to_owned(),
678        );
679        assert!(inbound.send(opened_session(1, "session-1")).is_ok());
680        let session = client.start_session(StartSessionOptions::default()).await;
681        assert!(session.is_ok(), "the session opens");
682        let Ok(session) = session else {
683            return;
684        };
685
686        let held = Arc::new(Mutex::new(None::<Session>));
687        let (dropped_tx, dropped_rx) = tokio::sync::oneshot::channel::<bool>();
688        let (release_tx, release_rx) = tokio::sync::oneshot::channel::<()>();
689        let (done_tx, done_rx) = tokio::sync::oneshot::channel::<()>();
690        let signals = Arc::new(Mutex::new(Some((dropped_tx, release_rx, done_tx))));
691        let handler_held = Arc::clone(&held);
692        session.on_approval(move |_| {
693            let signals = lock(&signals).take();
694            let last = lock(&handler_held).take();
695            async move {
696                if let Some((dropped_tx, release_rx, done_tx)) = signals {
697                    let weak = last.as_ref().map(Session::downgrade);
698                    drop(last);
699                    let gone = weak.is_some_and(|weak| weak.upgrade().is_none());
700                    let _ = dropped_tx.send(gone);
701                    let _ = release_rx.await;
702                    let _ = done_tx.send(());
703                }
704                ApprovalDecisionInput {
705                    choice_id: "allow_once".to_owned(),
706                    feedback: None,
707                }
708            }
709        });
710        let route = session.downgrade();
711        *lock(&held) = Some(session);
712        if let Some(inner) = route.upgrade() {
713            inner.apply(approval_requested("approval-1"));
714        }
715
716        // A cancelled handler drops its senders, so each wait resolves.
717        assert_eq!(
718            dropped_rx.await.ok(),
719            Some(true),
720            "the handler dropped the session's last handle"
721        );
722        let _ = release_tx.send(());
723        assert!(
724            done_rx.await.is_ok(),
725            "dropping the session's last handle aborted the worker its handler runs on"
726        );
727        client.close().await;
728    }
729
730    /// The same approval offering only allow-once, so the worker has no deny
731    /// to send for an answer the host never offered.
732    fn allow_only_approval_requested(approval_id: &str) -> Notification {
733        let mut notification = approval_requested(approval_id);
734        if let Some(params) = notification.params.as_mut() {
735            params.insert(
736                "availableChoices".to_owned(),
737                serde_json::json!([{
738                    "choiceId": "allow_once",
739                    "label": "Allow once",
740                    "decision": "approved",
741                    "scope": "once"
742                }]),
743            );
744        }
745        notification
746    }
747
748    /// A handler that closes the client runs on the session's approval
749    /// worker, which `close()` cannot abort. Whatever that handler then
750    /// answers (a choice the host never offered, with or without a deny
751    /// offered, an offered allow, or the offered abort), the worker stops
752    /// there, so an approval routed to the session once `close()` has begun
753    /// reaches no handler.
754    #[tokio::test(flavor = "current_thread")]
755    async fn an_approval_routed_while_a_handler_closes_the_client_reaches_no_handler() {
756        let cases: [(&str, ApprovalFixture, &str); 4] = [
757            ("an allow and an abort", approval_requested, "not_offered"),
758            ("an allow and an abort", approval_requested, "allow_once"),
759            ("an allow and an abort", approval_requested, "abort"),
760            (
761                "only an allow",
762                allow_only_approval_requested,
763                "not_offered",
764            ),
765        ];
766        for (offered, approval, answer) in cases {
767            let (inbound, reads) = mpsc::unbounded_channel();
768            let client = Arc::new(MuseClient::with_command_id_minter(
769                ChannelTransport { inbound: reads },
770                SessionDurability::Durable,
771                || "command-1".to_owned(),
772            ));
773            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
774            let session = client.start_session(StartSessionOptions::default()).await;
775            assert!(session.is_ok(), "the session opens");
776            let Ok(session) = session else {
777                return;
778            };
779
780            let (routed_tx, mut routed) = mpsc::unbounded_channel::<String>();
781            let (closed_tx, closed_rx) = tokio::sync::oneshot::channel::<()>();
782            let (release_tx, release_rx) = tokio::sync::oneshot::channel::<()>();
783            let (answered_tx, answered_rx) = tokio::sync::oneshot::channel::<()>();
784            let signals = Arc::new(Mutex::new(Some((closed_tx, release_rx, answered_tx))));
785            let handler_client = Arc::clone(&client);
786            session.on_approval(move |request| {
787                let _ = routed_tx.send(request.approval_id);
788                let client = Arc::clone(&handler_client);
789                let signals = lock(&signals).take();
790                async move {
791                    if let Some((closed_tx, release_rx, answered_tx)) = signals {
792                        client.close().await;
793                        let _ = closed_tx.send(());
794                        let _ = release_rx.await;
795                        let _ = answered_tx.send(());
796                    }
797                    ApprovalDecisionInput {
798                        choice_id: answer.to_owned(),
799                        feedback: None,
800                    }
801                }
802            });
803            session.inner.apply(approval("approval-1"));
804            assert!(closed_rx.await.is_ok(), "the handler closed the client");
805            assert_eq!(routed.recv().await.as_deref(), Some("approval-1"));
806            // A frame the connection read before its close took effect, which
807            // its dispatcher still hands over.
808            session.inner.apply(approval("approval-2"));
809            let _ = release_tx.send(());
810            assert!(answered_rx.await.is_ok(), "the closing handler answered");
811
812            // Wait until the worker routes again or stops, however many polls
813            // that takes. A worker that routes again and then stops has both
814            // ready, so the route is read first.
815            let rerouted = tokio::select! {
816                biased;
817                approval_id = routed.recv() => approval_id,
818                () = session.inner.approval.worker_stopped() => None,
819            };
820            assert_eq!(
821                rerouted, None,
822                "after answering {answer:?} to an approval offering {offered}, the closing handler's worker routed another approval"
823            );
824        }
825    }
826
827    /// A transport end with no `close()` sets the client's transport-ended flag
828    /// before its sweep reaches each session. An approval the worker answers
829    /// in that window is refused with `TransportEnded`; the worker must stop
830    /// and leave the approval's turn to the sweep, which settles it as
831    /// transport ended, instead of failing it first. A session the sweep has
832    /// not reached stands in for that window.
833    #[tokio::test(flavor = "current_thread")]
834    async fn an_approval_answered_after_the_transport_ended_leaves_its_turn_to_the_sweep() {
835        let (inbound, reads) = mpsc::unbounded_channel();
836        let client = MuseClient::with_command_id_minter(
837            ChannelTransport { inbound: reads },
838            SessionDurability::Durable,
839            || "command-1".to_owned(),
840        );
841        assert!(inbound.send(opened_session(1, "session-1")).is_ok());
842        let session = client.start_session(StartSessionOptions::default()).await;
843        assert!(session.is_ok(), "the session opens");
844        let Ok(session) = session else {
845            return;
846        };
847        // The host goes away; a request made after that returns only once the
848        // transport-end sweep has run.
849        drop(inbound);
850        let ended = client
851            .start_session(StartSessionOptions::default())
852            .await
853            .err();
854        assert!(
855            matches!(ended, Some(crate::client::FacadeError::TransportEnded)),
856            "control: a request after the end sees TransportEnded, got {ended:?}"
857        );
858
859        // Same client, never registered with its router, so the sweep skips it.
860        let unsettled = Session::from_opening(
861            Arc::clone(&session.inner.client),
862            session.opening().clone(),
863            &[],
864            None,
865        );
866        let turn = unsettled.inner.claim_turn_for_ordering_tests("turn-1");
867        unsettled.inner.apply(approval_requested("approval-1"));
868        let completion = turn.completed();
869        let stopped = unsettled.inner.approval.worker_stopped();
870        // antipattern-ok(timeout-wrapper): failure-only cap; success ends when the worker stops or the turn settles
871        let settled = tokio::time::timeout(std::time::Duration::from_secs(5), async {
872            tokio::select! {
873                biased;
874                // A worker that fails the turn and then stops has both ready,
875                // so the turn is read first.
876                outcome = completion => Some(outcome),
877                () = stopped => None,
878            }
879        })
880        .await;
881        assert!(
882            matches!(settled, Ok(None)),
883            "a worker refused with TransportEnded must stop and leave the turn to the sweep, got {settled:?}"
884        );
885    }
886
887    /// The same window, met by the `approval/decide` request itself: the
888    /// transport ends after the worker minted its command id, so the decide
889    /// is cut short and returns `TransportEnded`. The worker must stop there
890    /// too.
891    #[tokio::test(flavor = "current_thread")]
892    async fn an_approval_decide_cut_short_by_the_transport_end_leaves_its_turn_to_the_sweep() {
893        let (inbound, reads) = mpsc::unbounded_channel();
894        assert!(inbound.send(opened_session(1, "session-1")).is_ok());
895        // The second id is the approval's: minting it ends the host's stream.
896        let host = Arc::new(Mutex::new(Some(inbound)));
897        let minted = Arc::new(std::sync::atomic::AtomicUsize::new(0));
898        let minter_host = Arc::clone(&host);
899        let client = MuseClient::with_command_id_minter(
900            ChannelTransport { inbound: reads },
901            SessionDurability::Durable,
902            move || {
903                if minted.fetch_add(1, std::sync::atomic::Ordering::Relaxed) == 1 {
904                    lock(&minter_host).take();
905                }
906                "command-1".to_owned()
907            },
908        );
909        let session = client.start_session(StartSessionOptions::default()).await;
910        assert!(session.is_ok(), "the session opens");
911        let Ok(session) = session else {
912            return;
913        };
914
915        // Same client, never registered with its router, so the sweep skips it.
916        let unsettled = Session::from_opening(
917            Arc::clone(&session.inner.client),
918            session.opening().clone(),
919            &[],
920            None,
921        );
922        let turn = unsettled.inner.claim_turn_for_ordering_tests("turn-1");
923        unsettled.inner.apply(approval_requested("approval-1"));
924        let completion = turn.completed();
925        let stopped = unsettled.inner.approval.worker_stopped();
926        // antipattern-ok(timeout-wrapper): failure-only cap; success ends when the worker stops or the turn settles
927        let settled = tokio::time::timeout(std::time::Duration::from_secs(5), async {
928            tokio::select! {
929                biased;
930                // A worker that fails the turn and then stops has both ready,
931                // so the turn is read first.
932                outcome = completion => Some(outcome),
933                () = stopped => None,
934            }
935        })
936        .await;
937        assert!(
938            lock(&host).is_none(),
939            "control: the worker minted the approval's command id"
940        );
941        assert!(
942            matches!(settled, Ok(None)),
943            "a decide cut short by the transport end must stop the worker and leave the turn to the sweep, got {settled:?}"
944        );
945    }
946
947    /// A connection that breaks with a read error fails every pending request
948    /// with that I/O error, and the driver's end then runs the transport-end
949    /// sweep. A worker whose `approval/decide` is pending at that moment must
950    /// stop without failing its turn, as it does for a clean transport end,
951    /// and leave the turn to that sweep.
952    #[tokio::test(flavor = "current_thread")]
953    async fn an_approval_decide_cut_short_by_a_read_error_leaves_its_turn_to_the_sweep() {
954        let client = MuseClient::new(
955            crate::session::state::tests::StartsThenFailsRead::new("approval/decide"),
956            SessionDurability::Durable,
957        );
958        let session = client.start_session(StartSessionOptions::default()).await;
959        assert!(session.is_ok(), "the session opens");
960        let Ok(session) = session else {
961            return;
962        };
963        // A turn of the registered session, which the sweep reaches.
964        let swept = session.inner.claim_turn_for_ordering_tests("turn-0");
965
966        // Same client, never registered with its router, so the sweep skips it.
967        let unsettled = Session::from_opening(
968            Arc::clone(&session.inner.client),
969            session.opening().clone(),
970            &[],
971            None,
972        );
973        let turn = unsettled.inner.claim_turn_for_ordering_tests("turn-1");
974        unsettled.inner.apply(approval_requested("approval-1"));
975        let completion = turn.completed();
976        let stopped = unsettled.inner.approval.worker_stopped();
977        // antipattern-ok(timeout-wrapper): failure-only cap; success ends when the worker stops or the turn settles
978        let settled = tokio::time::timeout(std::time::Duration::from_secs(5), async {
979            tokio::select! {
980                biased;
981                // A worker that fails the turn and then stops has both ready,
982                // so the turn is read first.
983                outcome = completion => Some(outcome),
984                () = stopped => None,
985            }
986        })
987        .await;
988        assert!(
989            matches!(settled, Ok(None)),
990            "a decide cut short by a read error must stop the worker and leave the turn to the sweep, got {settled:?}"
991        );
992        // Only the decide's write fails the read, so the sweep shows it was sent.
993        let swept = swept.completed();
994        // antipattern-ok(timeout-wrapper): failure-only cap; success ends when the sweep settles the registered turn
995        let outcome = tokio::time::timeout(std::time::Duration::from_secs(5), swept).await;
996        assert!(
997            matches!(outcome, Ok(Err(crate::client::FacadeError::TransportEnded))),
998            "control: the decide was sent and its read error's sweep settled the registered turn, got {outcome:?}"
999        );
1000    }
1001
1002    /// The same unrouted session, whose worker `close()` doesn't stop: the
1003    /// client starts closing right after the worker minted the approval's
1004    /// command id, so the decide is refused with `ClientClosed`. The worker
1005    /// must stop there without failing the turn.
1006    #[tokio::test(flavor = "current_thread")]
1007    async fn an_approval_decide_refused_by_a_closing_client_stops_without_failing_its_turn() {
1008        let (inbound, reads) = mpsc::unbounded_channel();
1009        assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1010        // The second id is the approval's: minting it starts the close.
1011        let closer = Arc::new(std::sync::OnceLock::<Weak<MuseClient>>::new());
1012        let minted = Arc::new(std::sync::atomic::AtomicUsize::new(0));
1013        let closing = Arc::new(std::sync::atomic::AtomicBool::new(false));
1014        let minter_closer = Arc::clone(&closer);
1015        let minter_closing = Arc::clone(&closing);
1016        let client = Arc::new(MuseClient::with_command_id_minter(
1017            ChannelTransport { inbound: reads },
1018            SessionDurability::Durable,
1019            move || {
1020                if minted.fetch_add(1, std::sync::atomic::Ordering::Relaxed) == 1
1021                    && let Some(client) = minter_closer.get().and_then(Weak::upgrade)
1022                {
1023                    let mut close = Box::pin(client.close());
1024                    let _ = poll_once(close.as_mut());
1025                    minter_closing.store(true, std::sync::atomic::Ordering::Relaxed);
1026                }
1027                "command-1".to_owned()
1028            },
1029        ));
1030        let _ = closer.set(Arc::downgrade(&client));
1031        let session = client.start_session(StartSessionOptions::default()).await;
1032        assert!(session.is_ok(), "the session opens");
1033        let Ok(session) = session else {
1034            return;
1035        };
1036
1037        // Same client, never registered with its router, so close() skips it.
1038        let unsettled = Session::from_opening(
1039            Arc::clone(&session.inner.client),
1040            session.opening().clone(),
1041            &[],
1042            None,
1043        );
1044        let turn = unsettled.inner.claim_turn_for_ordering_tests("turn-1");
1045        unsettled.inner.apply(approval_requested("approval-1"));
1046        let completion = turn.completed();
1047        let stopped = unsettled.inner.approval.worker_stopped();
1048        // antipattern-ok(timeout-wrapper): failure-only cap; success ends when the worker stops or the turn settles
1049        let settled = tokio::time::timeout(std::time::Duration::from_secs(5), async {
1050            tokio::select! {
1051                biased;
1052                // A worker that fails the turn and then stops has both ready,
1053                // so the turn is read first.
1054                outcome = completion => Some(outcome),
1055                () = stopped => None,
1056            }
1057        })
1058        .await;
1059        assert!(
1060            closing.load(std::sync::atomic::Ordering::Relaxed),
1061            "control: the client started closing as the approval's command id was minted"
1062        );
1063        assert!(
1064            matches!(settled, Ok(None)),
1065            "a decide refused by a closing client must stop the worker without failing its turn, got {settled:?}"
1066        );
1067    }
1068
1069    #[test]
1070    fn settled_turns_leave_session_routing_state() {
1071        let handle = TurnHandle::new("turn-1");
1072        let mut state = SessionState::default();
1073        state.turns.insert(
1074            "turn-1".to_owned(),
1075            TurnRoute {
1076                handle,
1077                item_ids: HashSet::from(["item-1".to_owned(), "item-2".to_owned()]),
1078            },
1079        );
1080        state
1081            .item_turns
1082            .insert("item-1".to_owned(), "turn-1".to_owned());
1083        state
1084            .item_turns
1085            .insert("item-2".to_owned(), "turn-1".to_owned());
1086
1087        assert!(state.settle_and_retire_turn("turn-1", |handle| {
1088            handle.fail(TurnWaitError::EventSourceFailed {
1089                message: "settled".to_owned(),
1090            });
1091        }));
1092        assert!(state.turns.is_empty());
1093        assert!(state.item_turns.is_empty());
1094    }
1095
1096    /// The gap hold's own bound. Frames applied
1097    /// straight through the session while a `view/gap` hole is still
1098    /// pending (its `view/page` never answered) are held; the frame past
1099    /// `MAX_HELD_GAP_FRAMES` fails the event source with the hold's message,
1100    /// not the connection's.
1101    #[test]
1102    fn frames_held_past_the_gap_hold_bound_fail_the_event_source() {
1103        let runtime = tokio::runtime::Builder::new_current_thread()
1104            .enable_all()
1105            .build();
1106        assert!(runtime.is_ok(), "caller runtime builds");
1107        let Ok(runtime) = runtime else {
1108            return;
1109        };
1110        runtime.block_on(async {
1111            let (outbound, inbound) = mpsc::unbounded_channel();
1112            let replies = std::collections::VecDeque::from([
1113                ("session/start", serde_json::json!({
1114                "jsonrpc": "2.0",
1115                "id": 0,
1116                "result": {
1117                    "session": {
1118                        "sessionId": "session-1",
1119                        "path": "/tmp/session.jsonl",
1120                        "status": "idle",
1121                        "activeTurnId": null,
1122                        "createdAt": "2026-09-29T00:00:00Z",
1123                        "updatedAt": "2026-09-29T00:00:00Z",
1124                        "workspaceRoot": null,
1125                        "providerId": null,
1126                        "modelId": null,
1127                        "turnCount": 0,
1128                        "forkedFrom": null
1129                    },
1130                    "viewCursor": "cursor-1"
1131                }
1132            })),
1133                ("session/start", serde_json::json!({
1134                "jsonrpc": "2.0",
1135                "id": 0,
1136                "result": {
1137                    "session": {
1138                        "sessionId": "session-2",
1139                        "path": "/tmp/session-2.jsonl",
1140                        "status": "idle",
1141                        "activeTurnId": null,
1142                        "createdAt": "2026-09-29T00:00:00Z",
1143                        "updatedAt": "2026-09-29T00:00:00Z",
1144                        "workspaceRoot": null,
1145                        "providerId": null,
1146                        "modelId": null,
1147                        "turnCount": 0,
1148                        "forkedFrom": null
1149                    },
1150                    "viewCursor": "cursor-1"
1151                }
1152            })),
1153            ]);
1154            let client = MuseClient::with_command_id_minter(
1155                RepliesOnWrite {
1156                    inbound,
1157                    outbound,
1158                    replies,
1159                },
1160                SessionDurability::Durable,
1161                || "command-1".to_owned(),
1162            );
1163            let session = client.start_session(StartSessionOptions::default()).await;
1164            assert!(session.is_ok(), "session opens");
1165            let Ok(session) = session else {
1166                return;
1167            };
1168            let notification = |method: &str, params: serde_json::Value| Notification {
1169                jsonrpc: crate::msp::JsonRpcVersion::V2,
1170                method: method.to_owned(),
1171                params: params.as_object().cloned(),
1172                emitted_at_ms: None,
1173            };
1174            session.inner.apply(notification(
1175                "view/gap",
1176                serde_json::json!({"sessionId": "session-1", "after": "cursor-2", "next": "cursor-5"}),
1177            ));
1178            for index in 0..=gap_route::MAX_HELD_GAP_FRAMES {
1179                assert!(
1180                    lock(&session.inner.state).event_source_failure.is_none(),
1181                    "frame {index} is within the hold's bound"
1182                );
1183                session.inner.apply(notification(
1184                    "item/completed",
1185                    serde_json::json!({
1186                        "sessionId": "session-1",
1187                        "viewCursor": format!("cursor-{}", index + 6),
1188                    }),
1189                ));
1190            }
1191            assert_eq!(
1192                lock(&session.inner.state).event_source_failure,
1193                Some(TurnWaitError::EventSourceFailed {
1194                    message: "notification backlog exceeded for this session behind a pending \
1195                              delivery gap"
1196                        .to_owned(),
1197                })
1198            );
1199            // Robust continuity under this fault: the refusal is
1200            // scoped to that session; the client still correlates responses
1201            // and opens another.
1202            let survivor = client.start_session(StartSessionOptions::default()).await;
1203            assert!(
1204                survivor.is_ok_and(|survivor| survivor.session_id() == "session-2"),
1205                "another session on the same client survives the hold bound"
1206            );
1207            client.close().await;
1208        });
1209    }
1210
1211    fn opened_session(id: i64, session_id: &str) -> String {
1212        format!(
1213            "{}\n",
1214            serde_json::json!({
1215                "jsonrpc": "2.0",
1216                "id": id,
1217                "result": {
1218                    "session": {
1219                        "sessionId": session_id,
1220                        "path": "/tmp/session.jsonl",
1221                        "status": "idle",
1222                        "activeTurnId": null,
1223                        "createdAt": "2026-09-29T00:00:00Z",
1224                        "updatedAt": "2026-09-29T00:00:00Z",
1225                        "workspaceRoot": null,
1226                        "providerId": null,
1227                        "modelId": null,
1228                        "turnCount": 0,
1229                        "forkedFrom": null
1230                    },
1231                    "viewCursor": "cursor-1"
1232                }
1233            })
1234        )
1235    }
1236
1237    fn item_completed(session_id: &str, item_id: &str) -> Notification {
1238        Notification {
1239            jsonrpc: crate::msp::JsonRpcVersion::V2,
1240            method: "item/completed".to_owned(),
1241            params: serde_json::json!({
1242                "sessionId": session_id,
1243                "viewCursor": format!("cursor-{item_id}"),
1244                "sourceRange": {
1245                    "stream": {"kind": "run", "id": "turn-1"},
1246                    "first": {"id": "event-1", "sequence": 1},
1247                    "last": {"id": "event-1", "sequence": 1}
1248                },
1249                "item": {
1250                    "itemId": item_id,
1251                    "kind": "agentMessage",
1252                    "turnId": "turn-1",
1253                    "revision": 1,
1254                    "status": "completed",
1255                    "text": "reply"
1256                }
1257            })
1258            .as_object()
1259            .cloned(),
1260            emitted_at_ms: None,
1261        }
1262    }
1263
1264    /// Once a session's event source fails
1265    /// on a lost event, its fold stops at the last applied event and reports
1266    /// not current; another session's fold keeps applying, and closing the
1267    /// client, with no fill pending and no later frame, leaves that fold
1268    /// current.
1269    #[test]
1270    fn a_lost_event_stops_only_its_own_session_fold() {
1271        let runtime = tokio::runtime::Builder::new_current_thread()
1272            .enable_all()
1273            .build();
1274        assert!(runtime.is_ok(), "caller runtime builds");
1275        let Ok(runtime) = runtime else {
1276            return;
1277        };
1278        runtime.block_on(async {
1279            let (inbound, reads) = mpsc::unbounded_channel();
1280            let client = MuseClient::with_command_id_minter(
1281                ChannelTransport { inbound: reads },
1282                SessionDurability::Durable,
1283                || "command-1".to_owned(),
1284            );
1285            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1286            let affected = client.start_session(StartSessionOptions::default()).await;
1287            assert!(affected.is_ok(), "the affected session opens");
1288            assert!(inbound.send(opened_session(2, "session-2")).is_ok());
1289            let unaffected = client.start_session(StartSessionOptions::default()).await;
1290            assert!(unaffected.is_ok(), "the unaffected session opens");
1291            let (Ok(affected), Ok(unaffected)) = (affected, unaffected) else {
1292                return;
1293            };
1294
1295            affected
1296                .inner
1297                .apply(item_completed("session-1", "item-before"));
1298            affected
1299                .inner
1300                .fail_event_source(TurnWaitError::EventSourceFailed {
1301                    message: "notification backlog exceeded for this session; close this client, then resume the session on a new client to continue".to_owned(),
1302                });
1303            assert!(
1304                affected.fold().is_stopped(),
1305                "the loss alone stops the fold"
1306            );
1307            assert!(
1308                !affected.fold().is_current(),
1309                "the loss alone ends currency"
1310            );
1311            affected
1312                .inner
1313                .apply(item_completed("session-1", "item-after"));
1314            affected.inner.apply(Notification {
1315                jsonrpc: crate::msp::JsonRpcVersion::V2,
1316                method: "userInput/requested".to_owned(),
1317                params: serde_json::json!({"sessionId": "session-1", "userInputId": "input-after"})
1318                    .as_object()
1319                    .cloned(),
1320                emitted_at_ms: None,
1321            });
1322            unaffected
1323                .inner
1324                .apply(item_completed("session-2", "item-other"));
1325
1326            {
1327                let fold = affected.fold();
1328                assert!(fold.item("item-before").is_some());
1329                assert!(
1330                    fold.item("item-after").is_none(),
1331                    "nothing folds across the lost event"
1332                );
1333                assert!(
1334                    fold.pending_user_inputs().is_empty(),
1335                    "a lost event stops questions too"
1336                );
1337                assert!(!fold.is_current(), "the fold says it is incomplete");
1338                assert!(fold.is_stopped(), "the fold says it stopped for good");
1339                assert!(fold.pending_gap().is_none(), "no gap names the loss");
1340            }
1341            {
1342                let fold = unaffected.fold();
1343                assert!(fold.item("item-other").is_some());
1344                assert!(fold.is_current());
1345                assert!(!fold.is_stopped());
1346            }
1347
1348            client.close().await;
1349            assert!(
1350                unaffected.fold().is_current(),
1351                "closing the client loses no event"
1352            );
1353            assert!(!unaffected.fold().is_stopped());
1354        });
1355    }
1356
1357    /// A source failure stops a cut
1358    /// fill before it wakes the failed turns, so a turn woken by close or by
1359    /// the transport's end never reads the pending gap as a fill still running.
1360    #[test]
1361    fn a_failed_turn_wakes_to_a_stopped_fold_when_its_fill_was_cut() {
1362        struct ReadFoldOnWake {
1363            session: Session,
1364            seen: std::sync::Mutex<Option<bool>>,
1365        }
1366        impl std::task::Wake for ReadFoldOnWake {
1367            fn wake(self: Arc<Self>) {
1368                self.wake_by_ref();
1369            }
1370            fn wake_by_ref(self: &Arc<Self>) {
1371                let mut seen = self
1372                    .seen
1373                    .lock()
1374                    .unwrap_or_else(std::sync::PoisonError::into_inner);
1375                if seen.is_none() {
1376                    *seen = Some(self.session.fold().is_stopped());
1377                }
1378            }
1379        }
1380        let cuts: [fn(&SessionInner); 2] = [
1381            |inner| inner.fail_event_source(TurnWaitError::ClientClosed),
1382            |inner| inner.transport_ended(false),
1383        ];
1384        for cut in cuts {
1385            let runtime = tokio::runtime::Builder::new_current_thread()
1386                .enable_all()
1387                .build();
1388            assert!(runtime.is_ok(), "caller runtime builds");
1389            let Ok(runtime) = runtime else {
1390                return;
1391            };
1392            runtime.block_on(async {
1393                let (inbound, reads) = mpsc::unbounded_channel();
1394                let client = MuseClient::with_command_id_minter(
1395                    ChannelTransport { inbound: reads },
1396                    SessionDurability::Durable,
1397                    || "command-1".to_owned(),
1398                );
1399                assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1400                let session = client.start_session(StartSessionOptions::default()).await;
1401                assert!(session.is_ok(), "the session opens");
1402                let Ok(session) = session else {
1403                    return;
1404                };
1405                let handle = TurnHandle::new("turn-1");
1406                let turn = handle.turn();
1407                lock(&session.inner.state).turns.insert(
1408                    "turn-1".to_owned(),
1409                    TurnRoute {
1410                        handle,
1411                        item_ids: HashSet::new(),
1412                    },
1413                );
1414                let reader = Arc::new(ReadFoldOnWake {
1415                    session: session.clone(),
1416                    seen: std::sync::Mutex::new(None),
1417                });
1418                let waker = Waker::from(Arc::clone(&reader));
1419                let mut completed = Box::pin(turn.completed());
1420                assert!(
1421                    completed
1422                        .as_mut()
1423                        .poll(&mut Context::from_waker(&waker))
1424                        .is_pending()
1425                );
1426                session.inner.mirror_gap(Some(&crate::msp::ViewGapParams {
1427                    session_id: "session-1".to_owned(),
1428                    after: "cursor-2".to_owned(),
1429                    next: "cursor-3".to_owned(),
1430                }));
1431
1432                cut(&session.inner);
1433                let seen = *reader
1434                    .seen
1435                    .lock()
1436                    .unwrap_or_else(std::sync::PoisonError::into_inner);
1437                assert_eq!(seen, Some(true), "the woken turn reads a stopped fold");
1438                drop(completed);
1439                client.close().await;
1440            });
1441        }
1442    }
1443
1444    /// The close failure itself stops a
1445    /// fold whose fill it cuts, so a hole recorded just before the walker is
1446    /// aborted cannot read as a fill still running.
1447    #[test]
1448    fn a_client_closed_failure_stops_a_fold_whose_fill_it_cuts() {
1449        let runtime = tokio::runtime::Builder::new_current_thread()
1450            .enable_all()
1451            .build();
1452        assert!(runtime.is_ok(), "caller runtime builds");
1453        let Ok(runtime) = runtime else {
1454            return;
1455        };
1456        runtime.block_on(async {
1457            let (inbound, reads) = mpsc::unbounded_channel();
1458            let client = MuseClient::with_command_id_minter(
1459                ChannelTransport { inbound: reads },
1460                SessionDurability::Durable,
1461                || "command-1".to_owned(),
1462            );
1463            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1464            let session = client.start_session(StartSessionOptions::default()).await;
1465            assert!(session.is_ok(), "the session opens");
1466            let Ok(session) = session else {
1467                return;
1468            };
1469            session.inner.mirror_gap(Some(&crate::msp::ViewGapParams {
1470                session_id: "session-1".to_owned(),
1471                after: "cursor-2".to_owned(),
1472                next: "cursor-3".to_owned(),
1473            }));
1474            assert!(!session.fold().is_stopped(), "the fill is still running");
1475            session.inner.fail_event_source(TurnWaitError::ClientClosed);
1476            let fold = session.fold();
1477            assert!(fold.pending_gap().is_some());
1478            assert!(fold.is_stopped(), "the close failure cut the fill");
1479            client.close().await;
1480        });
1481    }
1482
1483    /// A transport end cuts a pending
1484    /// gap fill, so it stops the fold there, whichever the walker sees first.
1485    #[test]
1486    fn transport_end_stops_a_fold_whose_fill_it_cuts() {
1487        let runtime = tokio::runtime::Builder::new_current_thread()
1488            .enable_all()
1489            .build();
1490        assert!(runtime.is_ok(), "caller runtime builds");
1491        let Ok(runtime) = runtime else {
1492            return;
1493        };
1494        runtime.block_on(async {
1495            let (inbound, reads) = mpsc::unbounded_channel();
1496            let client = MuseClient::with_command_id_minter(
1497                ChannelTransport { inbound: reads },
1498                SessionDurability::Durable,
1499                || "command-1".to_owned(),
1500            );
1501            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1502            let session = client.start_session(StartSessionOptions::default()).await;
1503            assert!(session.is_ok(), "the session opens");
1504            let Ok(session) = session else {
1505                return;
1506            };
1507            session.inner.mirror_gap(Some(&crate::msp::ViewGapParams {
1508                session_id: "session-1".to_owned(),
1509                after: "cursor-2".to_owned(),
1510                next: "cursor-3".to_owned(),
1511            }));
1512            assert!(!session.fold().is_stopped(), "the fill is still running");
1513
1514            session.inner.transport_ended(false);
1515            let fold = session.fold();
1516            assert!(fold.pending_gap().is_some());
1517            assert!(fold.is_stopped(), "nothing can fill the hole after the end");
1518            client.close().await;
1519        });
1520    }
1521
1522    /// Close cuts a pending gap fill
1523    /// at once, so it stops the fold there, before any transport end.
1524    #[test]
1525    fn close_stops_a_fold_whose_fill_it_cuts() {
1526        let runtime = tokio::runtime::Builder::new_current_thread()
1527            .enable_all()
1528            .build();
1529        assert!(runtime.is_ok(), "caller runtime builds");
1530        let Ok(runtime) = runtime else {
1531            return;
1532        };
1533        runtime.block_on(async {
1534            let (inbound, reads) = mpsc::unbounded_channel();
1535            let client = MuseClient::with_command_id_minter(
1536                ChannelTransport { inbound: reads },
1537                SessionDurability::Durable,
1538                || "command-1".to_owned(),
1539            );
1540            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1541            let session = client.start_session(StartSessionOptions::default()).await;
1542            assert!(session.is_ok(), "the session opens");
1543            let Ok(session) = session else {
1544                return;
1545            };
1546            session.inner.mirror_gap(Some(&crate::msp::ViewGapParams {
1547                session_id: "session-1".to_owned(),
1548                after: "cursor-2".to_owned(),
1549                next: "cursor-3".to_owned(),
1550            }));
1551            assert!(!session.fold().is_stopped(), "the fill is still running");
1552
1553            // Close's first, synchronous step; no transport end has run yet.
1554            drop(session.inner.begin_close());
1555            let fold = session.fold();
1556            assert!(fold.pending_gap().is_some());
1557            assert!(fold.is_stopped(), "nothing can fill the hole after close");
1558            client.close().await;
1559        });
1560    }
1561
1562    /// A frame that reaches a session
1563    /// after close is a late frame, so it never folds (a twin a gap page
1564    /// already served could repeat); the handoff accepted it, so dropping it
1565    /// stops the fold.
1566    #[test]
1567    fn a_frame_after_close_does_not_fold() {
1568        let runtime = tokio::runtime::Builder::new_current_thread()
1569            .enable_all()
1570            .build();
1571        assert!(runtime.is_ok(), "caller runtime builds");
1572        let Ok(runtime) = runtime else {
1573            return;
1574        };
1575        runtime.block_on(async {
1576            let (inbound, reads) = mpsc::unbounded_channel();
1577            let client = MuseClient::with_command_id_minter(
1578                ChannelTransport { inbound: reads },
1579                SessionDurability::Durable,
1580                || "command-1".to_owned(),
1581            );
1582            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1583            let session = client.start_session(StartSessionOptions::default()).await;
1584            assert!(session.is_ok(), "the session opens");
1585            let Ok(session) = session else {
1586                return;
1587            };
1588            session
1589                .inner
1590                .apply(item_completed("session-1", "item-before"));
1591            drop(session.inner.begin_close());
1592            session
1593                .inner
1594                .apply(item_completed("session-1", "item-after"));
1595
1596            {
1597                let fold = session.fold();
1598                assert!(fold.item("item-before").is_some());
1599                assert!(
1600                    fold.item("item-after").is_none(),
1601                    "the tail after close never folds"
1602                );
1603                assert!(fold.is_stopped(), "the dropped frame stops the fold");
1604                assert!(!fold.is_current());
1605            }
1606            client.close().await;
1607        });
1608    }
1609
1610    /// A loss after a re-open
1611    /// ends the question-event exception, so the fold then applies nothing.
1612    #[test]
1613    fn a_loss_after_a_reopen_stops_question_events() {
1614        let runtime = tokio::runtime::Builder::new_current_thread()
1615            .enable_all()
1616            .build();
1617        assert!(runtime.is_ok(), "caller runtime builds");
1618        let Ok(runtime) = runtime else {
1619            return;
1620        };
1621        runtime.block_on(async {
1622            let (inbound, reads) = mpsc::unbounded_channel();
1623            let client = MuseClient::with_command_id_minter(
1624                ChannelTransport { inbound: reads },
1625                SessionDurability::Durable,
1626                || "command-1".to_owned(),
1627            );
1628            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1629            let session = client.start_session(StartSessionOptions::default()).await;
1630            assert!(session.is_ok(), "the session opens");
1631            let Ok(session) = session else {
1632                return;
1633            };
1634            let question = |id: &str| Notification {
1635                jsonrpc: crate::msp::JsonRpcVersion::V2,
1636                method: "userInput/requested".to_owned(),
1637                params: serde_json::json!({"sessionId": "session-1", "userInputId": id})
1638                    .as_object()
1639                    .cloned(),
1640                emitted_at_ms: None,
1641            };
1642            session.mark_fold_reopened();
1643            session.inner.apply(question("input-before"));
1644            session
1645                .inner
1646                .fail_event_source(TurnWaitError::EventSourceFailed {
1647                    message: "notification backlog exceeded for this session; close this client, then resume the session on a new client to continue".to_owned(),
1648                });
1649            session.inner.apply(question("input-after"));
1650
1651            let pending: Vec<String> = session
1652                .fold()
1653                .pending_user_inputs()
1654                .iter()
1655                .filter_map(|input| input["userInputId"].as_str().map(str::to_owned))
1656                .collect();
1657            assert_eq!(
1658                pending,
1659                ["input-before"],
1660                "the re-opened fold took the first question; the loss stopped the second"
1661            );
1662            client.close().await;
1663        });
1664    }
1665
1666    /// Any other source failure
1667    /// after a re-open ends the question-event exception too: the session's
1668    /// turns fail with that first source failure, and its late frames never fold.
1669    #[test]
1670    fn a_close_after_a_reopen_stops_question_events() {
1671        let runtime = tokio::runtime::Builder::new_current_thread()
1672            .enable_all()
1673            .build();
1674        assert!(runtime.is_ok(), "caller runtime builds");
1675        let Ok(runtime) = runtime else {
1676            return;
1677        };
1678        runtime.block_on(async {
1679            let (inbound, reads) = mpsc::unbounded_channel();
1680            let client = MuseClient::with_command_id_minter(
1681                ChannelTransport { inbound: reads },
1682                SessionDurability::Durable,
1683                || "command-1".to_owned(),
1684            );
1685            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1686            let session = client.start_session(StartSessionOptions::default()).await;
1687            assert!(session.is_ok(), "the session opens");
1688            let Ok(session) = session else {
1689                return;
1690            };
1691            let question = |id: &str| Notification {
1692                jsonrpc: crate::msp::JsonRpcVersion::V2,
1693                method: "userInput/requested".to_owned(),
1694                params: serde_json::json!({"sessionId": "session-1", "userInputId": id})
1695                    .as_object()
1696                    .cloned(),
1697                emitted_at_ms: None,
1698            };
1699            session.mark_fold_reopened();
1700            session.inner.apply(question("input-before"));
1701            drop(session.inner.begin_close());
1702            session.inner.apply(question("input-after"));
1703
1704            let pending: Vec<String> = session
1705                .fold()
1706                .pending_user_inputs()
1707                .iter()
1708                .filter_map(|input| input["userInputId"].as_str().map(str::to_owned))
1709                .collect();
1710            assert_eq!(
1711                pending,
1712                ["input-before"],
1713                "the re-opened fold took the first question; the close stopped the second"
1714            );
1715            client.close().await;
1716        });
1717    }
1718
1719    /// A fold view holds no lock between
1720    /// reads, so a caller keeping one never holds up event application, and
1721    /// each read sees the events applied before it.
1722    #[test]
1723    fn a_fold_view_holds_no_lock_between_reads() {
1724        let runtime = tokio::runtime::Builder::new_current_thread()
1725            .enable_all()
1726            .build();
1727        assert!(runtime.is_ok(), "caller runtime builds");
1728        let Ok(runtime) = runtime else {
1729            return;
1730        };
1731        runtime.block_on(async {
1732            let (inbound, reads) = mpsc::unbounded_channel();
1733            let client = MuseClient::with_command_id_minter(
1734                ChannelTransport { inbound: reads },
1735                SessionDurability::Durable,
1736                || "command-1".to_owned(),
1737            );
1738            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1739            let session = client.start_session(StartSessionOptions::default()).await;
1740            assert!(session.is_ok(), "the session opens");
1741            let Ok(session) = session else {
1742                return;
1743            };
1744
1745            let view = session.fold();
1746            assert!(view.item("item-later").is_none());
1747            assert!(
1748                session.inner.fold.try_lock().is_ok(),
1749                "a kept view must not hold the fold lock"
1750            );
1751            session
1752                .inner
1753                .apply(item_completed("session-1", "item-later"));
1754            assert!(
1755                view.item("item-later").is_some(),
1756                "the next read sees the event applied after the last one"
1757            );
1758            client.close().await;
1759        });
1760    }
1761
1762    /// A second `view/gap` that extends a hole the walk is
1763    /// still paging moves the fold's pending hole to the walk's new target.
1764    #[test]
1765    fn an_extended_delivery_gap_moves_the_fold_to_the_new_target() {
1766        let runtime = tokio::runtime::Builder::new_current_thread()
1767            .enable_all()
1768            .build();
1769        assert!(runtime.is_ok(), "caller runtime builds");
1770        let Ok(runtime) = runtime else {
1771            return;
1772        };
1773        runtime.block_on(async {
1774            let (inbound, reads) = mpsc::unbounded_channel();
1775            let client = MuseClient::with_command_id_minter(
1776                ChannelTransport { inbound: reads },
1777                SessionDurability::Durable,
1778                || "command-1".to_owned(),
1779            );
1780            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1781            let session = client.start_session(StartSessionOptions::default()).await;
1782            assert!(session.is_ok(), "the session opens");
1783            let Ok(session) = session else {
1784                return;
1785            };
1786            let gap = |after: &str, next: &str| Notification {
1787                jsonrpc: crate::msp::JsonRpcVersion::V2,
1788                method: "view/gap".to_owned(),
1789                params: serde_json::json!({"sessionId": "session-1", "after": after, "next": next})
1790                    .as_object()
1791                    .cloned(),
1792                emitted_at_ms: None,
1793            };
1794
1795            session.inner.apply(gap("cursor-2", "cursor-3"));
1796            session.inner.apply(gap("cursor-3", "cursor-5"));
1797
1798            let fold = session.fold();
1799            assert!(!fold.is_current());
1800            let pending = fold
1801                .pending_gap()
1802                .map(|gap| (gap.after().to_owned(), gap.next().to_owned()));
1803            assert_eq!(
1804                pending,
1805                Some(("cursor-2".to_owned(), "cursor-5".to_owned()))
1806            );
1807            client.close().await;
1808        });
1809    }
1810
1811    /// The fold view reads each family the fold keeps:
1812    /// approvals, user inputs in order, accumulated deltas and the running
1813    /// turn.
1814    #[test]
1815    fn a_fold_view_reads_approvals_user_inputs_deltas_and_the_active_turn() {
1816        let runtime = tokio::runtime::Builder::new_current_thread()
1817            .enable_all()
1818            .build();
1819        assert!(runtime.is_ok(), "caller runtime builds");
1820        let Ok(runtime) = runtime else {
1821            return;
1822        };
1823        runtime.block_on(async {
1824            let (inbound, reads) = mpsc::unbounded_channel();
1825            let client = MuseClient::with_command_id_minter(
1826                ChannelTransport { inbound: reads },
1827                SessionDurability::Durable,
1828                || "command-1".to_owned(),
1829            );
1830            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1831            let session = client.start_session(StartSessionOptions::default()).await;
1832            assert!(session.is_ok(), "the session opens");
1833            let Ok(session) = session else {
1834                return;
1835            };
1836            let note = |method: &str, params: serde_json::Value| Notification {
1837                jsonrpc: crate::msp::JsonRpcVersion::V2,
1838                method: method.to_owned(),
1839                params: params.as_object().cloned(),
1840                emitted_at_ms: None,
1841            };
1842            let range = serde_json::json!({
1843                "stream": {"kind": "run", "id": "turn-9"},
1844                "first": {"id": "event-1", "sequence": 1},
1845                "last": {"id": "event-1", "sequence": 1}
1846            });
1847            for (approval_id, resolve) in [("approval-1", true), ("approval-2", false)] {
1848                session.inner.apply(note(
1849                    "approval/requested",
1850                    serde_json::json!({
1851                        "sessionId": "session-1",
1852                        "approvalId": approval_id,
1853                        "turnId": "turn-9",
1854                        "taskId": format!("task-{approval_id}"),
1855                        "itemId": format!("item-{approval_id}"),
1856                        "toolCallId": format!("call-{approval_id}"),
1857                        "toolName": "shell",
1858                        "rawArgs": "{}",
1859                        "viewCursor": format!("cursor-{approval_id}"),
1860                        "sourceRange": range,
1861                        "subject": {"kind": "shell", "command": "pwd"},
1862                        "currentRequirementId": {"approvalId": approval_id, "sourceIndex": 0},
1863                        "availableChoices": [],
1864                        "protectedWrite": false,
1865                        "judgeEscalated": false
1866                    }),
1867                ));
1868                if resolve {
1869                    session.inner.apply(note(
1870                        "approval/resolved",
1871                        serde_json::json!({"sessionId": "session-1", "approvalId": approval_id}),
1872                    ));
1873                }
1874            }
1875            for input in ["input-1", "input-2"] {
1876                session.inner.apply(note(
1877                    "userInput/requested",
1878                    serde_json::json!({"sessionId": "session-1", "userInputId": input}),
1879                ));
1880            }
1881            session.inner.apply(note(
1882                "userInput/settled",
1883                serde_json::json!({"sessionId": "session-1", "userInputId": "input-1"}),
1884            ));
1885            session.inner.apply(note(
1886                "turn/started",
1887                serde_json::json!({
1888                    "sessionId": "session-1",
1889                    "viewCursor": "cursor-t",
1890                    "sourceRange": range,
1891                    "turnId": "turn-9",
1892                    "commandId": "command-9"
1893                }),
1894            ));
1895            session.inner.apply(note(
1896                "item/started",
1897                serde_json::json!({
1898                    "sessionId": "session-1",
1899                    "viewCursor": "cursor-i",
1900                    "sourceRange": range,
1901                    "item": {
1902                        "itemId": "item-a",
1903                        "kind": "agentMessage",
1904                        "turnId": "turn-9",
1905                        "revision": 1,
1906                        "status": "inProgress",
1907                        "text": ""
1908                    }
1909                }),
1910            ));
1911            session.inner.apply(note(
1912                "item/delta",
1913                serde_json::json!({
1914                    "sessionId": "session-1",
1915                    "viewCursor": "cursor-d",
1916                    "itemId": "item-a",
1917                    "delta": "hi"
1918                }),
1919            ));
1920
1921            let fold = session.fold();
1922            assert!(fold.pending_approval("approval-1").is_none());
1923            assert!(fold.resolved_approval("approval-1").is_some());
1924            assert!(fold.pending_approval("approval-2").is_some());
1925            assert!(fold.resolved_approval("approval-2").is_none());
1926            let ids = |inputs: Vec<serde_json::Value>| -> Vec<String> {
1927                inputs
1928                    .iter()
1929                    .filter_map(|input| input["userInputId"].as_str().map(str::to_owned))
1930                    .collect()
1931            };
1932            assert_eq!(ids(fold.pending_user_inputs()), ["input-2"]);
1933            assert_eq!(ids(fold.settled_user_inputs()), ["input-1"]);
1934            assert!(fold.pending_user_input("input-2").is_some());
1935            assert!(fold.settled_user_input("input-1").is_some());
1936            assert_eq!(fold.accumulated("item-a", "text"), Some("hi".to_owned()));
1937            assert_eq!(fold.active_turn_id(), Some("turn-9".to_owned()));
1938            client.close().await;
1939        });
1940    }
1941
1942    /// The fold view lists the item and turn ids it holds
1943    /// in first-seen order, so a caller can walk a resumed fold without the
1944    /// raw opening; a later update to a held id does not move it.
1945    #[test]
1946    fn a_fold_view_lists_item_and_turn_ids_in_first_seen_order() {
1947        let runtime = tokio::runtime::Builder::new_current_thread()
1948            .enable_all()
1949            .build();
1950        assert!(runtime.is_ok(), "caller runtime builds");
1951        let Ok(runtime) = runtime else {
1952            return;
1953        };
1954        runtime.block_on(async {
1955            let (inbound, reads) = mpsc::unbounded_channel();
1956            let client = MuseClient::with_command_id_minter(
1957                ChannelTransport { inbound: reads },
1958                SessionDurability::Durable,
1959                || "command-1".to_owned(),
1960            );
1961            assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1962            let session = client.start_session(StartSessionOptions::default()).await;
1963            assert!(session.is_ok(), "the session opens");
1964            let Ok(session) = session else {
1965                return;
1966            };
1967            let note = |method: &str, params: serde_json::Value| Notification {
1968                jsonrpc: crate::msp::JsonRpcVersion::V2,
1969                method: method.to_owned(),
1970                params: params.as_object().cloned(),
1971                emitted_at_ms: None,
1972            };
1973            // Eight ids each, neither alphabetical nor shared between the two
1974            // lists, so HashMap iteration cannot pass by luck.
1975            let order = ["e", "b", "g", "a", "h", "c", "f", "d"];
1976            for (revision, id) in [(1, "e"), (1, "b"), (1, "g"), (1, "a"), (2, "b")]
1977                .into_iter()
1978                .chain([(1, "h"), (1, "c"), (1, "f"), (1, "d"), (2, "e")])
1979            {
1980                session.inner.apply(note(
1981                    "item/updated",
1982                    serde_json::json!({
1983                        "sessionId": "session-1",
1984                        "viewCursor": format!("cursor-{id}-{revision}"),
1985                        "item": {"itemId": format!("item-{id}"), "revision": revision}
1986                    }),
1987                ));
1988            }
1989            for id in order.iter().rev().chain(["d", "a"].iter()) {
1990                session.inner.apply(note(
1991                    "turn/started",
1992                    serde_json::json!({
1993                        "sessionId": "session-1",
1994                        "viewCursor": format!("cursor-turn-{id}"),
1995                        "turnId": format!("turn-{id}"),
1996                        "commandId": format!("command-{id}")
1997                    }),
1998                ));
1999            }
2000
2001            let fold = session.fold();
2002            assert_eq!(
2003                fold.item_ids(),
2004                order.map(|id| format!("item-{id}")),
2005                "items list in first-seen order; updates do not move them"
2006            );
2007            assert_eq!(
2008                fold.turn_ids(),
2009                order
2010                    .map(|id| format!("turn-{id}"))
2011                    .into_iter()
2012                    .rev()
2013                    .collect::<Vec<_>>(),
2014                "turns list in first-seen order; repeats do not move them"
2015            );
2016            client.close().await;
2017        });
2018    }
2019
2020    #[test]
2021    fn source_failure_settlement_records_first_cause_and_clears_routes() {
2022        let handle = TurnHandle::new("turn-1");
2023        let turn = handle.turn();
2024        let mut state = SessionState::default();
2025        state.turns.insert(
2026            "turn-1".to_owned(),
2027            TurnRoute {
2028                handle,
2029                item_ids: HashSet::from(["item-1".to_owned()]),
2030            },
2031        );
2032        state
2033            .item_turns
2034            .insert("item-1".to_owned(), "turn-1".to_owned());
2035
2036        state.settle_source_failure(TurnWaitError::ClientClosed);
2037        state.settle_source_failure(TurnWaitError::SourceClosed);
2038
2039        assert_eq!(
2040            state.event_source_failure,
2041            Some(TurnWaitError::ClientClosed)
2042        );
2043        assert!(state.turns.is_empty());
2044        assert!(state.item_turns.is_empty());
2045        let mut completed = turn.completed();
2046        assert!(matches!(
2047            poll_once(completed.as_mut()),
2048            Poll::Ready(Err(crate::errors::MuseError::ClientClosed))
2049        ));
2050    }
2051
2052    #[test]
2053    fn dropping_send_user_turn_retires_its_pending_command() {
2054        let runtime = tokio::runtime::Builder::new_current_thread()
2055            .enable_all()
2056            .build();
2057        assert!(runtime.is_ok(), "caller runtime builds");
2058        let Ok(runtime) = runtime else {
2059            return;
2060        };
2061        runtime.block_on(async {
2062            let (inbound, reads) = mpsc::unbounded_channel();
2063            let queued = inbound.send(format!(
2064                "{}\n",
2065                serde_json::json!({
2066                    "jsonrpc": "2.0",
2067                    "id": 1,
2068                    "result": {
2069                        "session": {
2070                            "sessionId": "session-1",
2071                            "path": "/tmp/session.jsonl",
2072                            "status": "idle",
2073                            "activeTurnId": null,
2074                            "createdAt": "2026-09-29T00:00:00Z",
2075                            "updatedAt": "2026-09-29T00:00:00Z",
2076                            "workspaceRoot": null,
2077                            "providerId": null,
2078                            "modelId": null,
2079                            "turnCount": 0,
2080                            "forkedFrom": null
2081                        },
2082                        "viewCursor": "cursor-1"
2083                    }
2084                })
2085            ));
2086            assert!(queued.is_ok(), "session response queued");
2087            let client = MuseClient::with_command_id_minter(
2088                ChannelTransport { inbound: reads },
2089                SessionDurability::Durable,
2090                || "command-1".to_owned(),
2091            );
2092            let session = client.start_session(StartSessionOptions::default()).await;
2093            assert!(session.is_ok(), "session opens");
2094            let Ok(session) = session else {
2095                return;
2096            };
2097            let mut turn = Box::pin(session.send_user_turn(SendUserTurnOptions::default()));
2098            assert!(poll_once(turn.as_mut()).is_pending());
2099            assert_eq!(lock(&session.inner.state).pending_commands.len(), 1);
2100
2101            drop(turn);
2102
2103            assert!(lock(&session.inner.state).pending_commands.is_empty());
2104            client.close().await;
2105        });
2106    }
2107
2108    #[test]
2109    fn turn_claimed_after_client_close_keeps_closed_error() {
2110        let runtime = tokio::runtime::Builder::new_current_thread()
2111            .enable_all()
2112            .build();
2113        assert!(runtime.is_ok(), "caller runtime builds");
2114        let Ok(runtime) = runtime else {
2115            return;
2116        };
2117        runtime.block_on(async {
2118            let (inbound, reads) = mpsc::unbounded_channel();
2119            let queued = inbound.send(format!(
2120                "{}\n",
2121                serde_json::json!({
2122                    "jsonrpc": "2.0",
2123                    "id": 1,
2124                    "result": {
2125                        "session": {
2126                            "sessionId": "session-1",
2127                            "path": "/tmp/session.jsonl",
2128                            "status": "idle",
2129                            "activeTurnId": null,
2130                            "createdAt": "2026-09-29T00:00:00Z",
2131                            "updatedAt": "2026-09-29T00:00:00Z",
2132                            "workspaceRoot": null,
2133                            "providerId": null,
2134                            "modelId": null,
2135                            "turnCount": 0,
2136                            "forkedFrom": null
2137                        },
2138                        "viewCursor": "cursor-1"
2139                    }
2140                })
2141            ));
2142            assert!(queued.is_ok(), "session response queued");
2143            let client = MuseClient::with_command_id_minter(
2144                ChannelTransport { inbound: reads },
2145                SessionDurability::Durable,
2146                || "command-1".to_owned(),
2147            );
2148            let session = client.start_session(StartSessionOptions::default()).await;
2149            assert!(session.is_ok(), "session opens");
2150            let Ok(session) = session else {
2151                return;
2152            };
2153
2154            client.close().await;
2155            session.inner.transport_ended(false);
2156            let turn = session.inner.claim_turn("turn-after-close");
2157
2158            assert!(matches!(
2159                turn.completed().await,
2160                Err(crate::errors::MuseError::ClientClosed)
2161            ));
2162        });
2163    }
2164
2165    #[test]
2166    fn settled_alias_capacity_evicts_instead_of_poisoning_the_session() {
2167        let mut state = SessionState::default();
2168        state.pending_commands.insert("command-1".to_owned());
2169        for sequence in 0..=MAX_SETTLED_TURN_ALIASES {
2170            let turn_id = format!("turn-{sequence}");
2171            let handle = TurnHandle::new(&turn_id);
2172            state.turns.insert(
2173                turn_id.clone(),
2174                TurnRoute {
2175                    handle,
2176                    item_ids: HashSet::new(),
2177                },
2178            );
2179            assert!(state.settle_and_retire_turn(&turn_id, |handle| {
2180                handle.fail(TurnWaitError::EventSourceFailed {
2181                    message: "settled".to_owned(),
2182                });
2183            }));
2184        }
2185
2186        assert!(state.event_source_failure.is_none());
2187        assert_eq!(state.settled_turns.len(), MAX_SETTLED_TURN_ALIASES);
2188        assert!(
2189            state
2190                .settled_turns
2191                .contains_key(&format!("turn-{MAX_SETTLED_TURN_ALIASES}"))
2192        );
2193    }
2194
2195    /// The cap-refused record keeps the most recent `MAX_RETIRED_TURNS`
2196    /// refusals, and a live claim drops its entry from both its set and order.
2197    #[test]
2198    fn cap_refused_record_is_bounded_and_forgets_a_live_claim() {
2199        let mut state = SessionState::default();
2200        for sequence in 0..=MAX_RETIRED_TURNS {
2201            state.remember_cap_refused(&format!("turn-{sequence}"));
2202        }
2203        assert_eq!(state.cap_refused_turns.len(), MAX_RETIRED_TURNS);
2204        assert_eq!(state.cap_refused_turn_order.len(), MAX_RETIRED_TURNS);
2205        assert!(!state.settled_for_approvals("turn-0"));
2206        assert!(state.settled_for_approvals(&format!("turn-{MAX_RETIRED_TURNS}")));
2207
2208        state.forget_cap_refused("turn-1");
2209        assert!(!state.settled_for_approvals("turn-1"));
2210        assert_eq!(state.cap_refused_turn_order.len(), MAX_RETIRED_TURNS - 1);
2211        state.remember_cap_refused("turn-1");
2212        state.remember_cap_refused("turn-1");
2213        assert_eq!(state.cap_refused_turns.len(), MAX_RETIRED_TURNS);
2214        assert_eq!(state.cap_refused_turn_order.len(), MAX_RETIRED_TURNS);
2215        assert!(state.settled_for_approvals("turn-1"));
2216        // The record is approval routing's alone: notification acceptance
2217        // still follows the active-turn cap.
2218        assert!(state.accepts_turn_notification("turn-1"));
2219    }
2220
2221    #[test]
2222    fn a_resumed_session_holds_settled_aliases_until_released() {
2223        let mut state = SessionState::default();
2224        state.hold_settled_aliases = true;
2225        let handle = TurnHandle::new("turn-1");
2226        state.turns.insert(
2227            "turn-1".to_owned(),
2228            TurnRoute {
2229                handle,
2230                item_ids: HashSet::new(),
2231            },
2232        );
2233
2234        // Retired with no command in flight: only the hold keeps the alias.
2235        assert!(state.settle_and_retire_turn("turn-1", |handle| {
2236            handle.fail(TurnWaitError::EventSourceFailed {
2237                message: "settled".to_owned(),
2238            });
2239        }));
2240        assert!(state.settled_turns.contains_key("turn-1"));
2241        state.pending_commands.insert("command-other".to_owned());
2242        state.finish_pending_command("command-other");
2243        assert!(state.settled_turns.contains_key("turn-1"));
2244
2245        state.release_settled_alias_hold();
2246        assert!(state.settled_turns.is_empty());
2247    }
2248
2249    fn carried(session_id: &str, command_id: &str, turn_id: Option<&str>) -> PendingTurn {
2250        PendingTurn {
2251            session_id: session_id.to_owned(),
2252            command_id: command_id.to_owned(),
2253            options: SendUserTurnOptions::default(),
2254            turn_id: turn_id.map(str::to_owned),
2255        }
2256    }
2257
2258    /// A durable `session-1` resumed over `RepliesOnWrite`, which answers each
2259    /// later scripted method only once its request is written.
2260    async fn resumed_session(
2261        later: Vec<(&'static str, serde_json::Value)>,
2262    ) -> Option<(MuseClient, Session)> {
2263        let (outbound, inbound) = mpsc::unbounded_channel();
2264        let mut replies = std::collections::VecDeque::from([(
2265            "session/resume",
2266            serde_json::json!({
2267                "jsonrpc": "2.0",
2268                "id": 0,
2269                "result": {
2270                    "session": {
2271                        "sessionId": "session-1",
2272                        "path": "/tmp/session.jsonl",
2273                        "status": "idle",
2274                        "activeTurnId": null,
2275                        "createdAt": "2026-09-29T00:00:00Z",
2276                        "updatedAt": "2026-09-29T00:00:00Z",
2277                        "workspaceRoot": null,
2278                        "providerId": null,
2279                        "modelId": null,
2280                        "turnCount": 1,
2281                        "forkedFrom": null
2282                    },
2283                    "viewCursor": "cursor-1",
2284                    "history": {"mode": "inline", "items": [], "snapshot": null},
2285                    "pendingRequests": []
2286                }
2287            }),
2288        )]);
2289        replies.extend(later);
2290        let client = MuseClient::with_command_id_minter(
2291            RepliesOnWrite {
2292                inbound,
2293                outbound,
2294                replies,
2295            },
2296            SessionDurability::Durable,
2297            || "command-resume".to_owned(),
2298        );
2299        let session = client
2300            .resume_session(ResumeSessionOptions {
2301                session_id: "session-1".to_owned(),
2302                ..ResumeSessionOptions::default()
2303            })
2304            .await;
2305        assert!(session.is_ok(), "session resumes");
2306        Some((client, session.ok()?))
2307    }
2308
2309    /// Applies a turn's terminal synchronously, as the dispatcher would.
2310    fn apply_turn_completed(session: &Session, turn_id: &str) {
2311        session.inner.apply(Notification {
2312            jsonrpc: crate::msp::JsonRpcVersion::V2,
2313            method: "turn/completed".to_owned(),
2314            params: serde_json::json!({
2315                "sessionId": "session-1",
2316                "viewCursor": "cursor-2",
2317                "sourceRange": {
2318                    "stream": {"kind": "run", "id": turn_id},
2319                    "first": {"id": "event-1", "sequence": 1},
2320                    "last": {"id": "event-1", "sequence": 1}
2321                },
2322                "turnId": turn_id,
2323                "terminal": "completed",
2324                "durationMs": 5
2325            })
2326            .as_object()
2327            .cloned(),
2328            emitted_at_ms: None,
2329        });
2330    }
2331
2332    #[test]
2333    fn a_refused_resolve_reconnect_keeps_the_hold_for_the_corrected_call() {
2334        let runtime = tokio::runtime::Builder::new_current_thread()
2335            .enable_all()
2336            .build();
2337        assert!(runtime.is_ok(), "caller runtime builds");
2338        let Ok(runtime) = runtime else {
2339            return;
2340        };
2341        runtime.block_on(async {
2342            // The refused call writes nothing, so this answers the corrected one.
2343            let answer = serde_json::json!({
2344                "jsonrpc": "2.0",
2345                "id": 0,
2346                "result": {
2347                    "commandId": "command-own",
2348                    "status": "accepted",
2349                    "turnId": "turn-1",
2350                    "startedNewTurn": true,
2351                    "disposition": "started"
2352                }
2353            });
2354            let Some((client, session)) = resumed_session(vec![("turn/start", answer)]).await
2355            else {
2356                return;
2357            };
2358            // turn-1 finished before any resolve_reconnect: only the hold keeps it.
2359            apply_turn_completed(&session, "turn-1");
2360            assert!(
2361                lock(&session.inner.state)
2362                    .settled_turns
2363                    .contains_key("turn-1")
2364            );
2365            let own = carried("session-1", "command-own", Some("turn-1"));
2366
2367            let refused = session
2368                .resolve_reconnect(vec![
2369                    own.clone(),
2370                    carried("session-2", "command-foreign", None),
2371                ])
2372                .await;
2373
2374            assert!(matches!(
2375                refused,
2376                Err(crate::errors::MuseError::Protocol(_))
2377            ));
2378            assert!(
2379                lock(&session.inner.state)
2380                    .settled_turns
2381                    .contains_key("turn-1"),
2382                "a refused call keeps the hold for the corrected call"
2383            );
2384            let corrected = session.resolve_reconnect(vec![own]).await;
2385            let live = corrected
2386                .ok()
2387                .and_then(|mut resolved| resolved.pop())
2388                .and_then(|resolution| resolution.result.ok());
2389            assert!(
2390                matches!(live, Some(Reconnected::Live(_))),
2391                "the corrected call follows turn-1"
2392            );
2393            if let Some(Reconnected::Live(turn)) = live {
2394                assert!(matches!(
2395                    turn.completed().await,
2396                    Ok(TurnOutcome::Completed { .. })
2397                ));
2398            }
2399            client.close().await;
2400        });
2401    }
2402
2403    #[test]
2404    fn an_empty_resolve_reconnect_releases_the_hold() {
2405        let runtime = tokio::runtime::Builder::new_current_thread()
2406            .enable_all()
2407            .build();
2408        assert!(runtime.is_ok(), "caller runtime builds");
2409        let Ok(runtime) = runtime else {
2410            return;
2411        };
2412        runtime.block_on(async {
2413            let Some((client, session)) = resumed_session(Vec::new()).await else {
2414                return;
2415            };
2416            apply_turn_completed(&session, "turn-1");
2417            assert!(
2418                lock(&session.inner.state)
2419                    .settled_turns
2420                    .contains_key("turn-1")
2421            );
2422
2423            let resolved = session.resolve_reconnect(Vec::new()).await;
2424
2425            assert!(matches!(resolved.as_deref(), Ok([])));
2426            assert!(!lock(&session.inner.state).hold_settled_aliases);
2427            assert!(lock(&session.inner.state).settled_turns.is_empty());
2428            client.close().await;
2429        });
2430    }
2431
2432    #[test]
2433    fn a_cancelled_resolve_reconnect_releases_the_hold() {
2434        let runtime = tokio::runtime::Builder::new_current_thread()
2435            .enable_all()
2436            .build();
2437        assert!(runtime.is_ok(), "caller runtime builds");
2438        let Ok(runtime) = runtime else {
2439            return;
2440        };
2441        runtime.block_on(async {
2442            // No scripted `turn/start` answer: the resend stays in flight.
2443            let Some((client, session)) = resumed_session(Vec::new()).await else {
2444                return;
2445            };
2446            assert!(lock(&session.inner.state).hold_settled_aliases);
2447            let mut resolving = Box::pin(session.resolve_reconnect(vec![carried(
2448                "session-1",
2449                "command-own",
2450                None,
2451            )]));
2452            assert!(poll_once(resolving.as_mut()).is_pending());
2453            assert!(lock(&session.inner.state).hold_settled_aliases);
2454
2455            drop(resolving);
2456
2457            assert!(!lock(&session.inner.state).hold_settled_aliases);
2458            client.close().await;
2459        });
2460    }
2461
2462    #[test]
2463    fn an_answered_turn_refused_a_route_at_the_cap_stays_pending() {
2464        let runtime = tokio::runtime::Builder::new_current_thread()
2465            .enable_all()
2466            .build();
2467        assert!(runtime.is_ok(), "caller runtime builds");
2468        let Ok(runtime) = runtime else {
2469            return;
2470        };
2471        runtime.block_on(async {
2472            let answer = serde_json::json!({
2473                "jsonrpc": "2.0",
2474                "id": 0,
2475                "result": {
2476                    "commandId": "command-resume",
2477                    "status": "accepted",
2478                    "turnId": "turn-over-cap",
2479                    "startedNewTurn": true,
2480                    "disposition": "started"
2481                }
2482            });
2483            let Some((client, session)) = resumed_session(vec![("turn/start", answer)]).await
2484            else {
2485                return;
2486            };
2487            {
2488                let mut state = lock(&session.inner.state);
2489                for sequence in 0..MAX_ACTIVE_TURNS {
2490                    let turn_id = format!("live-{sequence}");
2491                    state
2492                        .turns
2493                        .insert(turn_id.clone(), TurnRoute::new(&turn_id));
2494                }
2495            }
2496
2497            // The server started the turn, but the cap refuses it a route: until
2498            // that turn's terminal is routed here, it must stay pending.
2499            let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
2500            assert!(turn.is_ok(), "the answer is accepted");
2501            assert!(
2502                !lock(&session.inner.state)
2503                    .turns
2504                    .contains_key("turn-over-cap"),
2505                "the cap refused the turn a route"
2506            );
2507
2508            let pending = session.pending();
2509            assert_eq!(pending.len(), 1);
2510            assert_eq!(pending[0].command_id(), "command-resume");
2511            assert_eq!(pending[0].turn_id(), Some("turn-over-cap"));
2512            // All 128 routes are still taken, so its own terminal is not applied.
2513            apply_turn_completed(&session, "turn-over-cap");
2514            assert_eq!(
2515                session.pending().len(),
2516                1,
2517                "a terminal under a full cap is not applied"
2518            );
2519            client.close().await;
2520        });
2521    }
2522
2523    #[test]
2524    fn a_cap_refused_turn_leaves_pending_once_its_terminal_arrives() {
2525        let runtime = tokio::runtime::Builder::new_current_thread()
2526            .enable_all()
2527            .build();
2528        assert!(runtime.is_ok(), "caller runtime builds");
2529        let Ok(runtime) = runtime else {
2530            return;
2531        };
2532        runtime.block_on(async {
2533            let answer = serde_json::json!({
2534                "jsonrpc": "2.0",
2535                "id": 0,
2536                "result": {
2537                    "commandId": "command-resume",
2538                    "status": "accepted",
2539                    "turnId": "turn-over-cap",
2540                    "startedNewTurn": true,
2541                    "disposition": "started"
2542                }
2543            });
2544            let Some((client, session)) = resumed_session(vec![("turn/start", answer)]).await
2545            else {
2546                return;
2547            };
2548            {
2549                let mut state = lock(&session.inner.state);
2550                for sequence in 0..MAX_ACTIVE_TURNS {
2551                    let turn_id = format!("live-{sequence}");
2552                    state
2553                        .turns
2554                        .insert(turn_id.clone(), TurnRoute::new(&turn_id));
2555                }
2556            }
2557            let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
2558            assert!(turn.is_ok(), "the answer is accepted");
2559            assert!(
2560                !lock(&session.inner.state)
2561                    .turns
2562                    .contains_key("turn-over-cap"),
2563                "the cap refused the turn a route"
2564            );
2565            assert_eq!(session.pending().len(), 1);
2566
2567            // The cap is transient: once a live turn ends, the refused turn's own
2568            // terminal is routed here, and that answers its submission.
2569            apply_turn_completed(&session, "live-0");
2570            assert_eq!(
2571                session.pending().len(),
2572                1,
2573                "another turn's terminal answers nothing"
2574            );
2575            apply_turn_completed(&session, "turn-over-cap");
2576
2577            assert!(session.pending().is_empty());
2578            client.close().await;
2579        });
2580    }
2581
2582    /// What a turn's waiter could see of the session when settlement woke it.
2583    #[derive(Debug)]
2584    enum SeenOnWake {
2585        /// The settler held the session state when it woke the waiter. It
2586        /// retires the turn before releasing it because
2587        /// `SessionState::settle_and_retire_turn` does both in one `&mut self`
2588        /// call.
2589        Locked,
2590        Unlocked {
2591            still_routed: bool,
2592            new_route_fits: bool,
2593        },
2594    }
2595
2596    /// A waker that looks at the session state the moment it is woken: tokio's
2597    /// `watch` wakes it inline, inside the settle.
2598    struct LookOnWake {
2599        inner: Arc<SessionInner>,
2600        turn_id: &'static str,
2601        seen: Mutex<Option<SeenOnWake>>,
2602    }
2603
2604    impl std::task::Wake for LookOnWake {
2605        fn wake(self: Arc<Self>) {
2606            self.wake_by_ref();
2607        }
2608
2609        fn wake_by_ref(self: &Arc<Self>) {
2610            let seen = match self.inner.state.try_lock() {
2611                Ok(state) => SeenOnWake::Unlocked {
2612                    still_routed: state.turns.contains_key(self.turn_id),
2613                    new_route_fits: state.accepts_turn_notification("turn-after"),
2614                },
2615                Err(std::sync::TryLockError::WouldBlock) => SeenOnWake::Locked,
2616                Err(std::sync::TryLockError::Poisoned(state)) => {
2617                    let state = state.into_inner();
2618                    SeenOnWake::Unlocked {
2619                        still_routed: state.turns.contains_key(self.turn_id),
2620                        new_route_fits: state.accepts_turn_notification("turn-after"),
2621                    }
2622                }
2623            };
2624            *lock(&self.seen) = Some(seen);
2625        }
2626    }
2627
2628    /// A server terminal retires its turn under the lock that wakes
2629    /// `completed()`, so a caller that resumes at the active-turn cap can open
2630    /// a new route at once instead of being refused.
2631    fn settled_turn_is_retired_before_its_waiter_wakes(
2632        turn_id: &'static str,
2633        settle: fn(&Session, &str),
2634    ) {
2635        let runtime = tokio::runtime::Builder::new_current_thread()
2636            .enable_all()
2637            .build();
2638        assert!(runtime.is_ok(), "caller runtime builds");
2639        let Ok(runtime) = runtime else {
2640            return;
2641        };
2642        runtime.block_on(async {
2643            let answer = serde_json::json!({
2644                "jsonrpc": "2.0",
2645                "id": 0,
2646                "result": {
2647                    "commandId": "command-resume",
2648                    "status": "accepted",
2649                    "turnId": "turn-after",
2650                    "startedNewTurn": true,
2651                    "disposition": "started"
2652                }
2653            });
2654            let Some((client, session)) = resumed_session(vec![("turn/start", answer)]).await
2655            else {
2656                return;
2657            };
2658            let turn = session.inner.claim_turn(turn_id);
2659            {
2660                let mut state = lock(&session.inner.state);
2661                for sequence in 1..MAX_ACTIVE_TURNS {
2662                    let live = format!("live-{sequence}");
2663                    state.turns.insert(live.clone(), TurnRoute::new(&live));
2664                }
2665                assert!(
2666                    !state.accepts_turn_notification("turn-after"),
2667                    "the active-turn cap is full"
2668                );
2669            }
2670            let look = Arc::new(LookOnWake {
2671                inner: Arc::clone(&session.inner),
2672                turn_id,
2673                seen: Mutex::new(None),
2674            });
2675            let waker = Waker::from(Arc::clone(&look));
2676            let mut context = Context::from_waker(&waker);
2677            let mut completed = turn.completed();
2678            assert!(completed.as_mut().poll(&mut context).is_pending());
2679
2680            settle(&session, turn_id);
2681
2682            let seen = lock(&look.seen).take();
2683            assert!(
2684                matches!(
2685                    seen,
2686                    Some(
2687                        SeenOnWake::Locked
2688                            | SeenOnWake::Unlocked {
2689                                still_routed: false,
2690                                new_route_fits: true
2691                            }
2692                    )
2693                ),
2694                "the woken waiter saw the settled turn still holding its route: {seen:?}"
2695            );
2696            assert!(matches!(
2697                completed.as_mut().poll(&mut context),
2698                Poll::Ready(Ok(_))
2699            ));
2700            let after = session.send_user_turn(SendUserTurnOptions::default()).await;
2701            assert!(after.is_ok(), "the next turn/start is accepted");
2702            assert!(
2703                lock(&session.inner.state).turns.contains_key("turn-after"),
2704                "a turn started right after completed() resolves gets a route"
2705            );
2706            client.close().await;
2707        });
2708    }
2709
2710    #[test]
2711    fn a_completed_turn_is_retired_before_its_waiter_wakes() {
2712        settled_turn_is_retired_before_its_waiter_wakes("turn-1", apply_turn_completed);
2713    }
2714
2715    #[test]
2716    fn an_unqueued_turn_is_retired_before_its_waiter_wakes() {
2717        settled_turn_is_retired_before_its_waiter_wakes("turn-queued", |session, turn_id| {
2718            session.inner.apply(Notification {
2719                jsonrpc: crate::msp::JsonRpcVersion::V2,
2720                method: "turn/unqueued".to_owned(),
2721                params: serde_json::json!({
2722                    "sessionId": "session-1",
2723                    "viewCursor": "cursor-2",
2724                    "sourceRange": {
2725                        "stream": {"kind": "session", "id": "session-1"},
2726                        "first": {"id": "event-1", "sequence": 1},
2727                        "last": {"id": "event-1", "sequence": 1}
2728                    },
2729                    "turnId": turn_id,
2730                    "commandId": "command-1"
2731                })
2732                .as_object()
2733                .cloned(),
2734                emitted_at_ms: None,
2735            });
2736        });
2737    }
2738
2739    #[test]
2740    fn settle_and_retire_turn_settles_the_routed_handle_then_retires_it() {
2741        let mut state = SessionState::default();
2742        let handle = TurnHandle::new("turn-1");
2743        state.turns.insert(
2744            "turn-1".to_owned(),
2745            TurnRoute {
2746                handle: handle.clone(),
2747                item_ids: HashSet::new(),
2748            },
2749        );
2750
2751        assert!(state.settle_and_retire_turn("turn-1", |turn| {
2752            turn.fail(TurnWaitError::EventSourceFailed {
2753                message: "settled".to_owned(),
2754            });
2755        }));
2756        assert!(handle.is_settled());
2757        assert!(state.turns.is_empty());
2758
2759        let mut settled_unrouted = false;
2760        assert!(!state.settle_and_retire_turn("turn-unrouted", |_| settled_unrouted = true));
2761        assert!(
2762            !settled_unrouted,
2763            "an unrouted turn has no handle to settle"
2764        );
2765    }
2766
2767    #[test]
2768    fn retired_turns_reject_late_notification_recreation() {
2769        let mut state = SessionState::default();
2770        for sequence in 0..=(MAX_RETIRED_TURNS + MAX_ACTIVE_TURNS) {
2771            let turn_id = format!("turn-{sequence}");
2772            let handle = TurnHandle::new(&turn_id);
2773            state.turns.insert(
2774                turn_id.clone(),
2775                TurnRoute {
2776                    handle,
2777                    item_ids: HashSet::new(),
2778                },
2779            );
2780            assert!(state.settle_and_retire_turn(&turn_id, |handle| {
2781                handle.fail(TurnWaitError::EventSourceFailed {
2782                    message: "settled".to_owned(),
2783                });
2784            }));
2785        }
2786
2787        assert!(!state.accepts_turn_notification(&format!("turn-{MAX_RETIRED_TURNS}")));
2788        for sequence in 0..=(MAX_RETIRED_TURNS + MAX_ACTIVE_TURNS) {
2789            let turn_id = format!("turn-{sequence}");
2790            if state.accepts_turn_notification(&turn_id) {
2791                state
2792                    .turns
2793                    .insert(turn_id.clone(), TurnRoute::new(&turn_id));
2794            }
2795        }
2796        assert_eq!(state.turns.len(), MAX_ACTIVE_TURNS);
2797        assert!(!state.accepts_turn_notification("another-late-turn"));
2798    }
2799
2800    #[test]
2801    fn retired_discard_history_is_bounded_per_session() {
2802        let mut state = SessionState::default();
2803        for sequence in 0..=MAX_RETIRED_TURNS {
2804            let turn_id = format!("turn-{sequence}");
2805            let command_id = format!("command-{sequence}");
2806            let handle = TurnHandle::new(&turn_id);
2807            let turn = handle.turn().with_discard(command_id);
2808            drop(turn);
2809            state.turns.insert(
2810                turn_id.clone(),
2811                TurnRoute {
2812                    handle,
2813                    item_ids: HashSet::new(),
2814                },
2815            );
2816            assert!(state.settle_and_retire_turn(&turn_id, |handle| {
2817                handle.fail(TurnWaitError::EventSourceFailed {
2818                    message: "settled".to_owned(),
2819                });
2820            }));
2821        }
2822
2823        assert_eq!(state.retired_turns.len(), MAX_RETIRED_TURNS);
2824        assert!(!state.is_command_discarded("command-0"));
2825        assert!(state.is_command_discarded(&format!("command-{MAX_RETIRED_TURNS}")));
2826    }
2827
2828    #[test]
2829    fn inline_history_resume_keeps_new_turns_runnable_past_the_active_turn_cap() {
2830        // A resumed session's finished history turns must not hold live
2831        // turn routes at resume, or the MAX_ACTIVE_TURNS cap refuses every new
2832        // turn.
2833        let runtime = tokio::runtime::Builder::new_current_thread()
2834            .enable_all()
2835            .build();
2836        assert!(runtime.is_ok(), "caller runtime builds");
2837        let Ok(runtime) = runtime else {
2838            return;
2839        };
2840        runtime.block_on(async {
2841            let (inbound, reads) = mpsc::unbounded_channel();
2842            let history: Vec<serde_json::Value> = (0..=MAX_ACTIVE_TURNS)
2843                .map(|sequence| {
2844                    serde_json::json!({
2845                        "itemId": format!("item-{sequence}"),
2846                        "kind": "agentMessage",
2847                        "turnId": format!("turn-{sequence}"),
2848                        "revision": 1,
2849                        "status": "completed",
2850                        "text": "earlier reply"
2851                    })
2852                })
2853                .collect();
2854            let queued = inbound.send(format!(
2855                "{}\n",
2856                serde_json::json!({
2857                    "jsonrpc": "2.0",
2858                    "id": 1,
2859                    "result": {
2860                        "session": {
2861                            "sessionId": "session-1",
2862                            "path": "/tmp/session.jsonl",
2863                            "status": "idle",
2864                            "activeTurnId": null,
2865                            "createdAt": "2026-09-29T00:00:00Z",
2866                            "updatedAt": "2026-09-29T00:00:00Z",
2867                            "workspaceRoot": null,
2868                            "providerId": null,
2869                            "modelId": null,
2870                            "turnCount": MAX_ACTIVE_TURNS + 1,
2871                            "forkedFrom": null
2872                        },
2873                        "viewCursor": "cursor-1",
2874                        "history": {"mode": "inline", "items": history, "snapshot": null},
2875                        "pendingRequests": []
2876                    }
2877                })
2878            ));
2879            assert!(queued.is_ok(), "resume response queued");
2880            let client = MuseClient::with_command_id_minter(
2881                ChannelTransport { inbound: reads },
2882                SessionDurability::Durable,
2883                || "command-1".to_owned(),
2884            );
2885            let session = client
2886                .resume_session(ResumeSessionOptions {
2887                    session_id: "session-1".to_owned(),
2888                    ..ResumeSessionOptions::default()
2889                })
2890                .await;
2891            assert!(session.is_ok(), "session resumes");
2892            let Ok(session) = session else {
2893                return;
2894            };
2895
2896            let queued = inbound.send(format!(
2897                "{}\n",
2898                serde_json::json!({
2899                    "jsonrpc": "2.0",
2900                    "id": 2,
2901                    "result": {
2902                        "commandId": "command-1",
2903                        "status": "accepted",
2904                        "turnId": "turn-new",
2905                        "startedNewTurn": true,
2906                        "disposition": "started"
2907                    }
2908                })
2909            ));
2910            assert!(queued.is_ok(), "turn/start response queued");
2911            let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
2912            assert!(turn.is_ok(), "turn/start is accepted");
2913            let Ok(turn) = turn else {
2914                return;
2915            };
2916            let mut completed = turn.completed();
2917            let first_poll = poll_once(completed.as_mut());
2918            assert!(
2919                first_poll.is_pending(),
2920                "a new turn after an inline-history resume must wait for its own terminal, got {first_poll:?}"
2921            );
2922            assert!(
2923                lock(&session.inner.state).turns.len() <= 1,
2924                "finished history turns must hold no live route; routes: {}",
2925                lock(&session.inner.state).turns.len()
2926            );
2927
2928            let queued = inbound.send(format!(
2929                "{}\n",
2930                serde_json::json!({
2931                    "jsonrpc": "2.0",
2932                    "method": "turn/completed",
2933                    "params": {
2934                        "sessionId": "session-1",
2935                        "viewCursor": "cursor-2",
2936                        "sourceRange": {
2937                            "stream": {"kind": "run", "id": "turn-new"},
2938                            "first": {"id": "event-1", "sequence": 1},
2939                            "last": {"id": "event-1", "sequence": 1}
2940                        },
2941                        "turnId": "turn-new",
2942                        "terminal": "completed",
2943                        "reason": null,
2944                        "durationMs": 5,
2945                        "timeToFirstTokenMs": 1,
2946                        "usage": null
2947                    }
2948                })
2949            ));
2950            assert!(queued.is_ok(), "turn/completed queued");
2951            let outcome = completed.await;
2952            assert!(
2953                matches!(outcome, Ok(TurnOutcome::Completed { .. })),
2954                "the new turn settles on its own terminal, got {outcome:?}"
2955            );
2956            client.close().await;
2957        });
2958    }
2959
2960    #[test]
2961    fn inline_history_resume_routes_the_running_turn_with_no_held_items() {
2962        // Resume opens the running turn's route even when the history
2963        // holds none of its items, and that turn's own terminal retires it.
2964        let runtime = tokio::runtime::Builder::new_current_thread()
2965            .enable_all()
2966            .build();
2967        assert!(runtime.is_ok(), "caller runtime builds");
2968        let Ok(runtime) = runtime else {
2969            return;
2970        };
2971        runtime.block_on(async {
2972            let (inbound, reads) = mpsc::unbounded_channel();
2973            let queued = inbound.send(format!(
2974                "{}\n",
2975                serde_json::json!({
2976                    "jsonrpc": "2.0",
2977                    "id": 1,
2978                    "result": {
2979                        "session": {
2980                            "sessionId": "session-1",
2981                            "path": "/tmp/session.jsonl",
2982                            "status": "running",
2983                            "activeTurnId": "turn-live",
2984                            "createdAt": "2026-09-29T00:00:00Z",
2985                            "updatedAt": "2026-09-29T00:00:00Z",
2986                            "workspaceRoot": null,
2987                            "providerId": null,
2988                            "modelId": null,
2989                            "turnCount": 2,
2990                            "forkedFrom": null
2991                        },
2992                        "viewCursor": "cursor-1",
2993                        "history": {
2994                            "mode": "inline",
2995                            "items": [
2996                                {
2997                                    "itemId": "item-old",
2998                                    "kind": "agentMessage",
2999                                    "turnId": "turn-old",
3000                                    "revision": 1,
3001                                    "status": "completed",
3002                                    "text": "earlier reply"
3003                                }
3004                            ],
3005                            "snapshot": null
3006                        },
3007                        "pendingRequests": []
3008                    }
3009                })
3010            ));
3011            assert!(queued.is_ok(), "resume response queued");
3012            let client = MuseClient::with_command_id_minter(
3013                ChannelTransport { inbound: reads },
3014                SessionDurability::Durable,
3015                || "command-1".to_owned(),
3016            );
3017            let session = client
3018                .resume_session(ResumeSessionOptions {
3019                    session_id: "session-1".to_owned(),
3020                    ..ResumeSessionOptions::default()
3021                })
3022                .await;
3023            assert!(session.is_ok(), "session resumes");
3024            let Ok(session) = session else {
3025                return;
3026            };
3027            {
3028                let state = lock(&session.inner.state);
3029                let routed: Vec<&str> = state.turns.keys().map(String::as_str).collect();
3030                assert_eq!(routed, ["turn-live"], "resume routes only the running turn");
3031            }
3032
3033            session.inner.apply(Notification {
3034                jsonrpc: crate::msp::JsonRpcVersion::V2,
3035                method: "turn/completed".to_owned(),
3036                params: serde_json::json!({
3037                    "sessionId": "session-1",
3038                    "viewCursor": "cursor-2",
3039                    "sourceRange": {
3040                        "stream": {"kind": "run", "id": "turn-live"},
3041                        "first": {"id": "event-1", "sequence": 1},
3042                        "last": {"id": "event-1", "sequence": 1}
3043                    },
3044                    "turnId": "turn-live",
3045                    "terminal": "completed",
3046                    "reason": null,
3047                    "durationMs": 5,
3048                    "timeToFirstTokenMs": 1,
3049                    "usage": null
3050                })
3051                .as_object()
3052                .cloned(),
3053                emitted_at_ms: None,
3054            });
3055            assert!(
3056                lock(&session.inner.state).turns.is_empty(),
3057                "the running turn's terminal retires its route"
3058            );
3059            client.close().await;
3060        });
3061    }
3062
3063    /// Where a resume serves its history: inline in `history.items`, or in a
3064    /// snapshot's `state.items` (`snapshot` mode, or `anchoredSnapshot` with
3065    /// its anchor).
3066    #[derive(Clone, Copy)]
3067    enum HistoryForm {
3068        Inline,
3069        Snapshot,
3070        AnchoredSnapshot,
3071        /// No history served (`none`, as a cursor resume answers).
3072        None,
3073    }
3074
3075    fn served_history(form: HistoryForm, items: serde_json::Value) -> serde_json::Value {
3076        match form {
3077            HistoryForm::Inline => {
3078                serde_json::json!({"mode": "inline", "items": items, "snapshot": null})
3079            }
3080            HistoryForm::None => serde_json::json!({
3081                "mode": "none",
3082                "noneReason": "cursorSuffix",
3083                "items": null,
3084                "snapshot": null
3085            }),
3086            HistoryForm::Snapshot | HistoryForm::AnchoredSnapshot => serde_json::json!({
3087                "mode": match form {
3088                    HistoryForm::AnchoredSnapshot => "anchoredSnapshot",
3089                    _ => "snapshot",
3090                },
3091                "items": null,
3092                "snapshot": {
3093                    "schemaVersion": 1,
3094                    "viewCursor": "cursor-1",
3095                    "anchor": match form {
3096                        HistoryForm::AnchoredSnapshot => serde_json::json!({
3097                            "boundaryCursor": "cursor-0",
3098                            "summarizedThrough": "anchor-0"
3099                        }),
3100                        _ => serde_json::Value::Null,
3101                    },
3102                    "state": {
3103                        "items": items,
3104                        "activeTurn": null,
3105                        "queuedTurns": [],
3106                        "pendingApprovals": [],
3107                        "pendingUserInputs": [],
3108                        "approvalMode": {"mode": "promptUnmatched", "source": "replay", "lastCommandId": null},
3109                        "effectiveModel": null,
3110                        "goal": null,
3111                        "todoList": null,
3112                        "branch": null,
3113                        "tokenUsage": {"promptTokens": 0, "outputTokens": 0, "totalTokens": 0},
3114                        "turnCount": 1
3115                    }
3116                }
3117            }),
3118        }
3119    }
3120
3121    #[test]
3122    fn inline_history_resume_opens_no_route_for_a_running_turn_last_turn_names() {
3123        resume_with_running_and_last_turn(HistoryForm::Inline, "turn-live");
3124    }
3125
3126    #[test]
3127    fn resume_routes_a_running_turn_while_last_turn_names_an_earlier_one() {
3128        // Control: only the turn `lastTurn` names is kept unrouted.
3129        resume_with_running_and_last_turn(HistoryForm::Inline, "turn-old");
3130    }
3131
3132    #[test]
3133    fn snapshot_history_resume_opens_no_route_for_a_running_turn_last_turn_names() {
3134        resume_with_running_and_last_turn(HistoryForm::Snapshot, "turn-live");
3135    }
3136
3137    #[test]
3138    fn none_history_resume_opens_no_route_for_a_running_turn_last_turn_names() {
3139        resume_with_running_and_last_turn(HistoryForm::None, "turn-live");
3140    }
3141
3142    #[test]
3143    fn anchored_snapshot_history_resume_opens_no_route_for_a_running_turn_last_turn_names() {
3144        resume_with_running_and_last_turn(HistoryForm::AnchoredSnapshot, "turn-live");
3145    }
3146
3147    /// Resumes with `turn-live` running and `lastTurn` naming `last_turn`.
3148    /// When a host reports as running a turn whose terminal `lastTurn`
3149    /// restates, the terminal is final: resume opens no route for it, so it
3150    /// holds no active-turn slot that no later terminal would free. A running
3151    /// turn `lastTurn` does not name keeps its route.
3152    fn resume_with_running_and_last_turn(form: HistoryForm, last_turn: &str) {
3153        let runtime = tokio::runtime::Builder::new_current_thread()
3154            .enable_all()
3155            .build();
3156        assert!(runtime.is_ok(), "caller runtime builds");
3157        let Ok(runtime) = runtime else {
3158            return;
3159        };
3160        runtime.block_on(async {
3161            let (inbound, reads) = mpsc::unbounded_channel();
3162            let queued = inbound.send(format!(
3163                "{}\n",
3164                serde_json::json!({
3165                    "jsonrpc": "2.0",
3166                    "id": 1,
3167                    "result": {
3168                        "session": {
3169                            "sessionId": "session-1",
3170                            "path": "/tmp/session.jsonl",
3171                            "status": "running",
3172                            "activeTurnId": "turn-live",
3173                            "createdAt": "2026-09-29T00:00:00Z",
3174                            "updatedAt": "2026-09-29T00:00:00Z",
3175                            "workspaceRoot": null,
3176                            "providerId": null,
3177                            "modelId": null,
3178                            "turnCount": 1,
3179                            "forkedFrom": null
3180                        },
3181                        "viewCursor": "cursor-1",
3182                        "history": served_history(form, serde_json::json!([
3183                                {
3184                                    "itemId": "item-live",
3185                                    "kind": "agentMessage",
3186                                    "turnId": "turn-live",
3187                                    "revision": 2,
3188                                    "status": "completed",
3189                                    "text": "final reply"
3190                                }
3191                            ])),
3192                        "pendingRequests": [],
3193                        "lastTurn": {"turnId": last_turn, "terminal": "completed"}
3194                    }
3195                })
3196            ));
3197            assert!(queued.is_ok(), "resume response queued");
3198            let client = MuseClient::with_command_id_minter(
3199                ChannelTransport { inbound: reads },
3200                SessionDurability::Durable,
3201                || "command-1".to_owned(),
3202            );
3203            let session = client
3204                .resume_session(ResumeSessionOptions {
3205                    session_id: "session-1".to_owned(),
3206                    ..ResumeSessionOptions::default()
3207                })
3208                .await;
3209            assert!(session.is_ok(), "session resumes");
3210            let Ok(session) = session else {
3211                return;
3212            };
3213            {
3214                let state = lock(&session.inner.state);
3215                assert_eq!(state.last_turn_id.as_deref(), Some(last_turn));
3216                assert_eq!(
3217                    state.turns.contains_key("turn-live"),
3218                    last_turn != "turn-live",
3219                    "a running turn gets a route at resume unless lastTurn names it"
3220                );
3221            }
3222            client.close().await;
3223        });
3224    }
3225
3226    #[test]
3227    fn inline_history_resume_keeps_the_running_turn_routed_and_settles_it() {
3228        resume_keeps_the_running_turn_routed_and_settles_it(HistoryForm::Inline);
3229    }
3230
3231    #[test]
3232    fn snapshot_history_resume_keeps_the_running_turn_routed_and_settles_it() {
3233        resume_keeps_the_running_turn_routed_and_settles_it(HistoryForm::Snapshot);
3234    }
3235
3236    #[test]
3237    fn anchored_snapshot_history_resume_keeps_the_running_turn_routed_and_settles_it() {
3238        resume_keeps_the_running_turn_routed_and_settles_it(HistoryForm::AnchoredSnapshot);
3239    }
3240
3241    fn resume_keeps_the_running_turn_routed_and_settles_it(form: HistoryForm) {
3242        // Resume must open the route for the turn the host still runs,
3243        // so its held items replay once, its live deltas still route, and its
3244        // own terminal settles it.
3245        let runtime = tokio::runtime::Builder::new_current_thread()
3246            .enable_all()
3247            .build();
3248        assert!(runtime.is_ok(), "caller runtime builds");
3249        let Ok(runtime) = runtime else {
3250            return;
3251        };
3252        runtime.block_on(async {
3253            let (inbound, reads) = mpsc::unbounded_channel();
3254            let queued = inbound.send(format!(
3255                "{}\n",
3256                serde_json::json!({
3257                    "jsonrpc": "2.0",
3258                    "id": 1,
3259                    "result": {
3260                        "session": {
3261                            "sessionId": "session-1",
3262                            "path": "/tmp/session.jsonl",
3263                            "status": "running",
3264                            "activeTurnId": "turn-live",
3265                            "createdAt": "2026-09-29T00:00:00Z",
3266                            "updatedAt": "2026-09-29T00:00:00Z",
3267                            "workspaceRoot": null,
3268                            "providerId": null,
3269                            "modelId": null,
3270                            "turnCount": 2,
3271                            "forkedFrom": null
3272                        },
3273                        "viewCursor": "cursor-1",
3274                        "history": served_history(form, serde_json::json!([
3275                                {
3276                                    "itemId": "item-old",
3277                                    "kind": "agentMessage",
3278                                    "turnId": "turn-old",
3279                                    "revision": 1,
3280                                    "status": "completed",
3281                                    "text": "finished reply"
3282                                },
3283                                {
3284                                    "itemId": "item-live",
3285                                    "kind": "agentMessage",
3286                                    "turnId": "turn-live",
3287                                    "revision": 1,
3288                                    "status": "inProgress",
3289                                    "text": "partial reply"
3290                                }
3291                            ])),
3292                        "pendingRequests": []
3293                    }
3294                })
3295            ));
3296            assert!(queued.is_ok(), "resume response queued");
3297            let client = MuseClient::with_command_id_minter(
3298                ChannelTransport { inbound: reads },
3299                SessionDurability::Durable,
3300                || "command-1".to_owned(),
3301            );
3302            let session = client
3303                .resume_session(ResumeSessionOptions {
3304                    session_id: "session-1".to_owned(),
3305                    ..ResumeSessionOptions::default()
3306                })
3307                .await;
3308            assert!(session.is_ok(), "session resumes");
3309            let Ok(session) = session else {
3310                return;
3311            };
3312            {
3313                let state = lock(&session.inner.state);
3314                let mut routed: Vec<&String> = state.turns.keys().collect();
3315                routed.sort();
3316                assert_eq!(
3317                    routed,
3318                    vec!["turn-live"],
3319                    "only the running turn holds a route after resume"
3320                );
3321            }
3322
3323            let queued = inbound.send(format!(
3324                "{}\n",
3325                serde_json::json!({
3326                    "jsonrpc": "2.0",
3327                    "id": 2,
3328                    "result": {
3329                        "commandId": "command-1",
3330                        "status": "accepted",
3331                        "turnId": "turn-live",
3332                        "startedNewTurn": false,
3333                        "disposition": "steered"
3334                    }
3335                })
3336            ));
3337            assert!(queued.is_ok(), "turn/start response queued");
3338            let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
3339            assert!(turn.is_ok(), "steered turn/start is accepted");
3340            let Ok(turn) = turn else {
3341                return;
3342            };
3343            let mut items = turn.items();
3344            let mut deltas = turn.deltas();
3345            let held = poll_once(std::pin::pin!(items.recv()));
3346            assert!(
3347                matches!(&held, Poll::Ready(Ok(Some(item))) if item.item_id == "item-live"),
3348                "the running turn's held item replays first, got {held:?}"
3349            );
3350
3351            let queued = inbound.send(format!(
3352                "{}\n{}\n",
3353                serde_json::json!({
3354                    "jsonrpc": "2.0",
3355                    "method": "item/delta",
3356                    "params": {
3357                        "sessionId": "session-1",
3358                        "viewCursor": "cursor-2",
3359                        "itemId": "item-live",
3360                        "field": "text",
3361                        "delta": " continued"
3362                    }
3363                }),
3364                serde_json::json!({
3365                    "jsonrpc": "2.0",
3366                    "method": "turn/completed",
3367                    "params": {
3368                        "sessionId": "session-1",
3369                        "viewCursor": "cursor-3",
3370                        "sourceRange": {
3371                            "stream": {"kind": "run", "id": "turn-live"},
3372                            "first": {"id": "event-1", "sequence": 1},
3373                            "last": {"id": "event-1", "sequence": 1}
3374                        },
3375                        "turnId": "turn-live",
3376                        "terminal": "completed",
3377                        "reason": null,
3378                        "durationMs": 5,
3379                        "timeToFirstTokenMs": 1,
3380                        "usage": null
3381                    }
3382                })
3383            ));
3384            assert!(queued.is_ok(), "item/delta and turn/completed queued");
3385            let delta = deltas.recv().await;
3386            assert!(
3387                matches!(&delta, Ok(Some(delta)) if delta.item_id == "item-live"),
3388                "a live delta for the replayed history item still routes, got {delta:?}"
3389            );
3390            let outcome = turn.completed().await;
3391            assert!(
3392                matches!(outcome, Ok(TurnOutcome::Completed { .. })),
3393                "the running turn settles on its own terminal, got {outcome:?}"
3394            );
3395            // open_route ran at resume (opening the route) and again at the
3396            // steered claim and the terminal (reusing it); the held item still
3397            // replays only once.
3398            let end = items.recv().await;
3399            assert!(
3400                matches!(end, Ok(None)),
3401                "the held item replays once, got {end:?}"
3402            );
3403            client.close().await;
3404        });
3405    }
3406
3407    #[test]
3408    fn inline_history_resume_replays_history_when_a_claim_opens_the_turn_first() {
3409        // When a claim, not a live event, first opens a finished
3410        // history turn's route, the claimed Turn replays that turn's history
3411        // once and in history order.
3412        let runtime = tokio::runtime::Builder::new_current_thread()
3413            .enable_all()
3414            .build();
3415        assert!(runtime.is_ok(), "caller runtime builds");
3416        let Ok(runtime) = runtime else {
3417            return;
3418        };
3419        runtime.block_on(async {
3420            let (inbound, reads) = mpsc::unbounded_channel();
3421            let queued = inbound.send(format!(
3422                "{}\n",
3423                serde_json::json!({
3424                    "jsonrpc": "2.0",
3425                    "id": 1,
3426                    "result": {
3427                        "session": {
3428                            "sessionId": "session-1",
3429                            "path": "/tmp/session.jsonl",
3430                            "status": "idle",
3431                            "activeTurnId": null,
3432                            "createdAt": "2026-09-29T00:00:00Z",
3433                            "updatedAt": "2026-09-29T00:00:00Z",
3434                            "workspaceRoot": null,
3435                            "providerId": null,
3436                            "modelId": null,
3437                            "turnCount": 1,
3438                            "forkedFrom": null
3439                        },
3440                        "viewCursor": "cursor-1",
3441                        "history": {
3442                            "mode": "inline",
3443                            "items": [
3444                                {
3445                                    "itemId": "item-first",
3446                                    "kind": "userMessage",
3447                                    "turnId": "turn-killed",
3448                                    "commandId": "command-1",
3449                                    "revision": 1,
3450                                    "status": "completed",
3451                                    "text": "retry me"
3452                                },
3453                                {
3454                                    "itemId": "item-second",
3455                                    "kind": "agentMessage",
3456                                    "turnId": "turn-killed",
3457                                    "revision": 1,
3458                                    "status": "completed",
3459                                    "text": "partial reply"
3460                                }
3461                            ],
3462                            "snapshot": null
3463                        },
3464                        "pendingRequests": []
3465                    }
3466                })
3467            ));
3468            assert!(queued.is_ok(), "resume response queued");
3469            let client = MuseClient::with_command_id_minter(
3470                ChannelTransport { inbound: reads },
3471                SessionDurability::Durable,
3472                || "command-1".to_owned(),
3473            );
3474            let session = client
3475                .resume_session(ResumeSessionOptions {
3476                    session_id: "session-1".to_owned(),
3477                    ..ResumeSessionOptions::default()
3478                })
3479                .await;
3480            assert!(session.is_ok(), "session resumes");
3481            let Ok(session) = session else {
3482                return;
3483            };
3484            assert!(
3485                lock(&session.inner.state).turns.is_empty(),
3486                "resume opens no route for the finished turn"
3487            );
3488
3489            // Only the retry answer is queued, so the claim opens the route
3490            // before any live event for the turn can.
3491            let queued = inbound.send(format!(
3492                "{}\n",
3493                serde_json::json!({
3494                    "jsonrpc": "2.0",
3495                    "id": 2,
3496                    "result": {
3497                        "commandId": "command-1",
3498                        "status": "accepted",
3499                        "turnId": "turn-killed",
3500                        "startedNewTurn": true,
3501                        "disposition": "started"
3502                    }
3503                })
3504            ));
3505            assert!(queued.is_ok(), "retry answer queued");
3506            let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
3507            assert!(turn.is_ok(), "same-command retry is accepted");
3508            let Ok(turn) = turn else {
3509                return;
3510            };
3511            let mut items = turn.items();
3512            // The claim opened the route, so the history is there before any
3513            // live event names the turn.
3514            let first = poll_once(std::pin::pin!(items.recv()));
3515            assert!(
3516                matches!(first, Poll::Ready(Ok(Some(_)))),
3517                "the claim replays the turn's history at once, got {first:?}"
3518            );
3519            let mut replayed = Vec::new();
3520            if let Poll::Ready(Ok(Some(item))) = first {
3521                replayed.push(item.item_id);
3522            }
3523
3524            // Applied directly, so the terminal settles before `completed()` is
3525            // awaited. The settle retires the turn under the lock that wakes the
3526            // waiter, so the waiter never sees it unretired.
3527            session.inner.apply(Notification {
3528                jsonrpc: crate::msp::JsonRpcVersion::V2,
3529                method: "turn/completed".to_owned(),
3530                params: serde_json::json!({
3531                    "sessionId": "session-1",
3532                    "viewCursor": "cursor-2",
3533                    "sourceRange": {
3534                        "stream": {"kind": "session", "id": "session-1"},
3535                        "first": {"id": "event-1", "sequence": 1},
3536                        "last": {"id": "event-1", "sequence": 1}
3537                    },
3538                    "turnId": "turn-killed",
3539                    "terminal": "cancelled",
3540                    "reason": "resume_reconcile:orphaned_by_process_loss"
3541                })
3542                .as_object()
3543                .cloned(),
3544                emitted_at_ms: None,
3545            });
3546            let outcome = turn.completed().await;
3547            assert!(
3548                matches!(outcome, Ok(TurnOutcome::Completed { .. })),
3549                "the claimed turn settles on its terminal, got {outcome:?}"
3550            );
3551            assert!(
3552                lock(&session.inner.state).item_turns.is_empty(),
3553                "the retired turn drops its replayed items' delta routes"
3554            );
3555            loop {
3556                match items.recv().await {
3557                    Ok(Some(item)) => replayed.push(item.item_id),
3558                    end => {
3559                        assert!(matches!(end, Ok(None)), "item stream failed: {end:?}");
3560                        break;
3561                    }
3562                }
3563            }
3564            assert_eq!(
3565                replayed,
3566                ["item-first", "item-second"],
3567                "the claimed turn replays its history once, in history order"
3568            );
3569            client.close().await;
3570        });
3571    }
3572
3573    #[test]
3574    fn inline_history_resume_replays_a_reconciled_turn_into_its_same_command_retry() {
3575        resume_replays_a_reconciled_turn_into_its_same_command_retry(HistoryForm::Inline);
3576    }
3577
3578    #[test]
3579    fn snapshot_history_resume_replays_a_reconciled_turn_into_its_same_command_retry() {
3580        resume_replays_a_reconciled_turn_into_its_same_command_retry(HistoryForm::Snapshot);
3581    }
3582
3583    #[test]
3584    fn a_newer_snapshot_schema_version_replays_no_turn_history() {
3585        // A snapshot newer than the fold this SDK understands, here in a shape
3586        // the current types cannot decode, still resumes: it is dropped before
3587        // decoding, so none of its items are indexed and no route opens at
3588        // resume.
3589        let runtime = tokio::runtime::Builder::new_current_thread()
3590            .enable_all()
3591            .build();
3592        assert!(runtime.is_ok(), "caller runtime builds");
3593        let Ok(runtime) = runtime else {
3594            return;
3595        };
3596        runtime.block_on(async {
3597            let mut history = served_history(
3598                HistoryForm::Snapshot,
3599                serde_json::json!([{
3600                    "itemId": "item-live",
3601                    "kind": "agentMessage",
3602                    "turnId": "turn-live",
3603                    "revision": 1,
3604                    "status": "inProgress",
3605                    "text": "partial reply"
3606                }]),
3607            );
3608            history["snapshot"]["schemaVersion"] = serde_json::json!(2);
3609            history["snapshot"]["state"] = serde_json::json!({"entries": []});
3610            let (inbound, reads) = mpsc::unbounded_channel();
3611            let queued = inbound.send(format!(
3612                "{}\n",
3613                serde_json::json!({
3614                    "jsonrpc": "2.0",
3615                    "id": 1,
3616                    "result": {
3617                        "session": {
3618                            "sessionId": "session-1",
3619                            "path": "/tmp/session.jsonl",
3620                            "status": "running",
3621                            "activeTurnId": "turn-live",
3622                            "createdAt": "2026-09-29T00:00:00Z",
3623                            "updatedAt": "2026-09-29T00:00:00Z",
3624                            "workspaceRoot": null,
3625                            "providerId": null,
3626                            "modelId": null,
3627                            "turnCount": 1,
3628                            "forkedFrom": null
3629                        },
3630                        "viewCursor": "cursor-1",
3631                        "history": history,
3632                        "pendingRequests": []
3633                    }
3634                })
3635            ));
3636            assert!(queued.is_ok(), "resume response queued");
3637            let client = MuseClient::with_command_id_minter(
3638                ChannelTransport { inbound: reads },
3639                SessionDurability::Durable,
3640                || "command-1".to_owned(),
3641            );
3642            let session = client
3643                .resume_session(ResumeSessionOptions {
3644                    session_id: "session-1".to_owned(),
3645                    ..ResumeSessionOptions::default()
3646                })
3647                .await;
3648            assert!(session.is_ok(), "session resumes");
3649            let Ok(session) = session else {
3650                return;
3651            };
3652            {
3653                let state = lock(&session.inner.state);
3654                assert!(
3655                    state.history_turn_items.is_empty(),
3656                    "a newer snapshot indexes no turn items"
3657                );
3658                assert!(
3659                    state.turns.is_empty(),
3660                    "a newer snapshot opens no route at resume"
3661                );
3662            }
3663            assert!(
3664                matches!(&session.inner.opening, SessionOpening::Resume(_)),
3665                "a resume opens with its resume result"
3666            );
3667            let SessionOpening::Resume(result) = &session.inner.opening else {
3668                return;
3669            };
3670            assert!(
3671                result.history.snapshot.is_none(),
3672                "the opening carries no snapshot the SDK cannot read"
3673            );
3674            assert_eq!(result.history.mode, crate::msp::HistoryMode::Snapshot);
3675            assert_eq!(
3676                session.dropped_snapshot_schema_version(),
3677                Some(2),
3678                "the session names the snapshot version it dropped"
3679            );
3680            client.close().await;
3681        });
3682    }
3683
3684    #[test]
3685    fn anchored_snapshot_history_resume_replays_a_reconciled_turn_into_its_same_command_retry() {
3686        resume_replays_a_reconciled_turn_into_its_same_command_retry(HistoryForm::AnchoredSnapshot);
3687    }
3688
3689    fn resume_replays_a_reconciled_turn_into_its_same_command_retry(form: HistoryForm) {
3690        // After a transport kill the host resumes with no active turn,
3691        // keeps the killed turn's userMessage in history, reconciles that turn
3692        // with a live terminal, and answers the same-command retry with the same
3693        // turn. The retried Turn must replay its history item, and resume must
3694        // still open no route for the finished turn.
3695        let runtime = tokio::runtime::Builder::new_current_thread()
3696            .enable_all()
3697            .build();
3698        assert!(runtime.is_ok(), "caller runtime builds");
3699        let Ok(runtime) = runtime else {
3700            return;
3701        };
3702        runtime.block_on(async {
3703            let (inbound, reads) = mpsc::unbounded_channel();
3704            let queued = inbound.send(format!(
3705                "{}\n",
3706                serde_json::json!({
3707                    "jsonrpc": "2.0",
3708                    "id": 1,
3709                    "result": {
3710                        "session": {
3711                            "sessionId": "session-1",
3712                            "path": "/tmp/session.jsonl",
3713                            "status": "idle",
3714                            "activeTurnId": null,
3715                            "createdAt": "2026-09-29T00:00:00Z",
3716                            "updatedAt": "2026-09-29T00:00:00Z",
3717                            "workspaceRoot": null,
3718                            "providerId": null,
3719                            "modelId": null,
3720                            "turnCount": 1,
3721                            "forkedFrom": null
3722                        },
3723                        "viewCursor": "cursor-1",
3724                        "history": served_history(form, serde_json::json!([
3725                                {
3726                                    "itemId": "item-killed",
3727                                    "kind": "userMessage",
3728                                    "turnId": "turn-killed",
3729                                    "commandId": "command-1",
3730                                    "revision": 1,
3731                                    "status": "completed",
3732                                    "text": "retry me"
3733                                }
3734                            ])),
3735                        "lastTurn": {
3736                            "turnId": "turn-killed",
3737                            "terminal": "cancelled",
3738                            "reason": "resume_reconcile:orphaned_by_process_loss"
3739                        },
3740                        "pendingRequests": []
3741                    }
3742                })
3743            ));
3744            assert!(queued.is_ok(), "resume response queued");
3745            let client = MuseClient::with_command_id_minter(
3746                ChannelTransport { inbound: reads },
3747                SessionDurability::Durable,
3748                || "command-1".to_owned(),
3749            );
3750            let session = client
3751                .resume_session(ResumeSessionOptions {
3752                    session_id: "session-1".to_owned(),
3753                    ..ResumeSessionOptions::default()
3754                })
3755                .await;
3756            assert!(session.is_ok(), "session resumes");
3757            let Ok(session) = session else {
3758                return;
3759            };
3760            assert!(
3761                lock(&session.inner.state).turns.is_empty(),
3762                "resume opens no route for the finished turn"
3763            );
3764
3765            // As on the real host, the reconciliation terminal arrives before the
3766            // retry answer: it opens the finished turn's route, replays its
3767            // history, settles and retires it into a held settled turn.
3768            session.inner.apply(Notification {
3769                jsonrpc: crate::msp::JsonRpcVersion::V2,
3770                method: "turn/completed".to_owned(),
3771                params: serde_json::json!({
3772                    "sessionId": "session-1",
3773                    "viewCursor": "cursor-2",
3774                    "sourceRange": {
3775                        "stream": {"kind": "session", "id": "session-1"},
3776                        "first": {"id": "event-1", "sequence": 1},
3777                        "last": {"id": "event-1", "sequence": 1}
3778                    },
3779                    "turnId": "turn-killed",
3780                    "terminal": "cancelled",
3781                    "reason": "resume_reconcile:orphaned_by_process_loss"
3782                })
3783                .as_object()
3784                .cloned(),
3785                emitted_at_ms: None,
3786            });
3787            {
3788                let state = lock(&session.inner.state);
3789                assert!(
3790                    state.settled_turns.contains_key("turn-killed"),
3791                    "the reconciled turn is held as a settled turn for its retry"
3792                );
3793                assert!(
3794                    !state.history_turn_items.contains_key("turn-killed"),
3795                    "opening the route takes the turn's history entry"
3796                );
3797                assert!(
3798                    state.item_turns.is_empty(),
3799                    "the retired turn drops its replayed items' delta routes"
3800                );
3801            }
3802
3803            let queued = inbound.send(format!(
3804                "{}\n",
3805                serde_json::json!({
3806                    "jsonrpc": "2.0",
3807                    "id": 2,
3808                    "result": {
3809                        "commandId": "command-1",
3810                        "status": "accepted",
3811                        "turnId": "turn-killed",
3812                        "startedNewTurn": true,
3813                        "disposition": "started"
3814                    }
3815                })
3816            ));
3817            assert!(queued.is_ok(), "retry answer queued");
3818            let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
3819            assert!(turn.is_ok(), "same-command retry is accepted");
3820            let Ok(turn) = turn else {
3821                return;
3822            };
3823            let outcome = turn.completed().await;
3824            assert!(
3825                matches!(outcome, Ok(TurnOutcome::Completed { .. })),
3826                "the retried turn settles on the reconciliation terminal, got {outcome:?}"
3827            );
3828            let mut items = turn.items();
3829            let replayed = items.recv().await;
3830            assert!(
3831                matches!(&replayed, Ok(Some(item)) if item.item_id == "item-killed"),
3832                "the retried turn replays its history userMessage, got {replayed:?}"
3833            );
3834            let end = items.recv().await;
3835            assert!(
3836                matches!(end, Ok(None)),
3837                "the history item replays once, got {end:?}"
3838            );
3839            client.close().await;
3840        });
3841    }
3842
3843    #[test]
3844    fn a_same_command_retry_of_a_turn_that_ended_before_the_resume_settles() {
3845        // The turn's terminal went out before the resume, so the resume
3846        // restates it as `lastTurn` and no live terminal follows. A
3847        // same-command retry gets the original ack; its Turn must still settle
3848        // rather than wait until close.
3849        let runtime = tokio::runtime::Builder::new_current_thread()
3850            .enable_all()
3851            .build();
3852        assert!(runtime.is_ok(), "caller runtime builds");
3853        let Ok(runtime) = runtime else {
3854            return;
3855        };
3856        runtime.block_on(async {
3857            let (inbound, reads) = mpsc::unbounded_channel();
3858            let queued = inbound.send(format!(
3859                "{}\n",
3860                serde_json::json!({
3861                    "jsonrpc": "2.0",
3862                    "id": 1,
3863                    "result": {
3864                        "session": {
3865                            "sessionId": "session-1",
3866                            "path": "/tmp/session.jsonl",
3867                            "status": "idle",
3868                            "activeTurnId": null,
3869                            "createdAt": "2026-09-29T00:00:00Z",
3870                            "updatedAt": "2026-09-29T00:00:00Z",
3871                            "workspaceRoot": null,
3872                            "providerId": null,
3873                            "modelId": null,
3874                            "turnCount": 1,
3875                            "forkedFrom": null
3876                        },
3877                        "viewCursor": "cursor-1",
3878                        "history": served_history(HistoryForm::Inline, serde_json::json!([
3879                                {
3880                                    "itemId": "item-done",
3881                                    "kind": "userMessage",
3882                                    "turnId": "turn-done",
3883                                    "commandId": "command-1",
3884                                    "revision": 1,
3885                                    "status": "completed",
3886                                    "text": "retry me"
3887                                }
3888                            ])),
3889                        "lastTurn": {"turnId": "turn-done", "terminal": "completed"},
3890                        "pendingRequests": []
3891                    }
3892                })
3893            ));
3894            assert!(queued.is_ok(), "resume response queued");
3895            let client = MuseClient::with_command_id_minter(
3896                ChannelTransport { inbound: reads },
3897                SessionDurability::Durable,
3898                || "command-1".to_owned(),
3899            );
3900            let session = client
3901                .resume_session(ResumeSessionOptions {
3902                    session_id: "session-1".to_owned(),
3903                    ..ResumeSessionOptions::default()
3904                })
3905                .await;
3906            assert!(session.is_ok(), "session resumes");
3907            let Ok(session) = session else {
3908                return;
3909            };
3910            let queued = inbound.send(format!(
3911                "{}\n",
3912                serde_json::json!({
3913                    "jsonrpc": "2.0",
3914                    "id": 2,
3915                    "result": {
3916                        "commandId": "command-1",
3917                        "status": "accepted",
3918                        "turnId": "turn-done",
3919                        "startedNewTurn": true,
3920                        "disposition": "started"
3921                    }
3922                })
3923            ));
3924            assert!(queued.is_ok(), "retry answer queued");
3925            let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
3926            assert!(turn.is_ok(), "same-command retry is accepted");
3927            let Ok(turn) = turn else {
3928                return;
3929            };
3930            let completion = turn.completed();
3931            // antipattern-ok(timeout-wrapper): failure-only cap; success ends when the retried turn settles
3932            let outcome = tokio::time::timeout(std::time::Duration::from_secs(5), completion).await;
3933            assert!(
3934                matches!(
3935                    &outcome,
3936                    Ok(Ok(TurnOutcome::Ended(last_turn)))
3937                        if last_turn.turn_id == "turn-done"
3938                            && last_turn.terminal == crate::msp::TurnTerminal::Completed
3939                ),
3940                "a retry of a turn that ended before the resume must settle Ended from its \
3941                 lastTurn, not wait for close, got {outcome:?}"
3942            );
3943            assert!(
3944                session.pending().is_empty(),
3945                "a retry settled from lastTurn leaves pending()"
3946            );
3947            client.close().await;
3948        });
3949    }
3950}