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