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