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