1

agents/rap-node-agent/internal/mesh/server_test.go

@@ -1643,6 +1643,44 @@ func TestRemoteWorkspaceAdapterSessionControlEndpointClosesSession(t *testing.T)
 		report["last_session_control_state"] != "closed" {
 		t.Fatalf("control report = %+v", report)
 	}
+	readiness, ok := report["adapter_runtime_readiness"].(map[string]any)
+	if !ok {
+		t.Fatalf("adapter runtime readiness missing from control report = %+v", report)
+	}
+	if readiness["schema_version"] != "rap.remote_workspace_adapter_runtime_readiness.v1" ||
+		readiness["status"] != "idle" ||
+		readiness["diagnostic_state"] != "last_session_terminal_or_expired" ||
+		readiness["ready"] != false ||
+		readiness["active_session_count"] != 0 ||
+		readiness["last_adapter_session_id"] != "rap-rw-adapter-session-aaaaaaaaaaaaaaaaaaaaaaaa" ||
+		readiness["last_session_state"] != "closed" {
+		t.Fatalf("invalid no-active-session readiness after close = %+v", readiness)
+	}
+	if _, ok := readiness["adapter_session_id"]; ok {
+		t.Fatalf("adapter_session_id should be absent without active session = %+v", readiness)
+	}
+	if _, ok := readiness["last_preflight"]; ok {
+		t.Fatalf("last_preflight should be absent without active session = %+v", readiness)
+	}
+	terminalSummary, ok := readiness["terminal_session_summary"].(map[string]any)
+	if !ok {
+		t.Fatalf("terminal session summary missing after close = %+v", readiness)
+	}
+	if terminalSummary["adapter_session_id"] != "rap-rw-adapter-session-aaaaaaaaaaaaaaaaaaaaaaaa" ||
+		terminalSummary["schema_version"] != "rap.remote_workspace_adapter_terminal_session_summary.v1" ||
+		!stringAnySliceContains(terminalSummary["summary_contract"], "adapter_session_id") ||
+		!stringAnySliceContains(terminalSummary["summary_contract"], "session_state") ||
+		!stringAnySliceContains(terminalSummary["summary_contract"], "reason") ||
+		!stringAnySliceContains(terminalSummary["summary_contract"], "controlled_at") ||
+		!boolMapValue(terminalSummary["summary_features"], "adapter_session_id") ||
+		!boolMapValue(terminalSummary["summary_features"], "session_state") ||
+		!boolMapValue(terminalSummary["summary_features"], "reason") ||
+		!boolMapValue(terminalSummary["summary_features"], "controlled_at") ||
+		terminalSummary["session_state"] != "closed" ||
+		terminalSummary["reason"] != "unit test close" ||
+		terminalSummary["controlled_at"] == "" {
+		t.Fatalf("invalid terminal session summary after close = %+v", terminalSummary)
+	}
 
 	resp, err = http.Post(controlURL, "application/json", bytes.NewReader([]byte(`{"action":"close","reason":"repeat close"}`)))
 	if err != nil {
@@ -1665,6 +1703,255 @@ func TestRemoteWorkspaceAdapterSessionControlEndpointClosesSession(t *testing.T)
 	}
 }
 
+func TestRemoteWorkspaceAdapterReadinessBeforeAnySessionHasNoTerminalSummary(t *testing.T) {
+	sink := NewRemoteWorkspaceFrameProbeSink()
+	report := sink.Report(time.Now().UTC())
+	readiness, ok := report["adapter_runtime_readiness"].(map[string]any)
+	if !ok {
+		t.Fatalf("adapter runtime readiness missing from report = %+v", report)
+	}
+	if readiness["schema_version"] != "rap.remote_workspace_adapter_runtime_readiness.v1" ||
+		readiness["status"] != "idle" ||
+		readiness["diagnostic_state"] != "waiting_for_session" ||
+		readiness["ready"] != false ||
+		readiness["active_session_count"] != 0 ||
+		readiness["terminal_session_count"] != 0 {
+		t.Fatalf("invalid empty readiness = %+v", readiness)
+	}
+	if _, ok := readiness["last_adapter_session_id"]; ok {
+		t.Fatalf("last_adapter_session_id should be absent before any session = %+v", readiness)
+	}
+	if _, ok := readiness["last_session_state"]; ok {
+		t.Fatalf("last_session_state should be absent before any session = %+v", readiness)
+	}
+	if _, ok := readiness["terminal_session_summary"]; ok {
+		t.Fatalf("terminal_session_summary should be absent before terminal history = %+v", readiness)
+	}
+	noSessionSummary, ok := readiness["no_session_summary"].(map[string]any)
+	if !ok {
+		t.Fatalf("no_session_summary should be present before any session = %+v", readiness)
+	}
+	if noSessionSummary["schema_version"] != "rap.remote_workspace_adapter_no_session_summary.v1" ||
+		!stringAnySliceContains(noSessionSummary["summary_contract"], "status") ||
+		!stringAnySliceContains(noSessionSummary["summary_contract"], "diagnostic_state") ||
+		!stringAnySliceContains(noSessionSummary["summary_contract"], "active_session_count") ||
+		!stringAnySliceContains(noSessionSummary["summary_contract"], "terminal_session_count") ||
+		!boolMapValue(noSessionSummary["summary_features"], "status") ||
+		!boolMapValue(noSessionSummary["summary_features"], "diagnostic_state") ||
+		!boolMapValue(noSessionSummary["summary_features"], "active_session_count") ||
+		!boolMapValue(noSessionSummary["summary_features"], "terminal_session_count") ||
+		noSessionSummary["status"] != "idle" ||
+		noSessionSummary["diagnostic_state"] != "waiting_for_session" ||
+		noSessionSummary["active_session_count"] != 0 ||
+		noSessionSummary["terminal_session_count"] != 0 {
+		t.Fatalf("invalid no-session summary before any session = %+v", noSessionSummary)
+	}
+	if _, ok := readiness["last_preflight"]; ok {
+		t.Fatalf("last_preflight should be absent before any session = %+v", readiness)
+	}
+}
+
+func TestRemoteWorkspaceAdapterReadinessSummaryExclusivity(t *testing.T) {
+	sink := NewRemoteWorkspaceFrameProbeSink()
+	freshReport := sink.Report(time.Now().UTC())
+	freshReadiness, ok := freshReport["adapter_runtime_readiness"].(map[string]any)
+	if !ok {
+		t.Fatalf("fresh readiness missing from report = %+v", freshReport)
+	}
+	if _, ok := freshReadiness["no_session_summary"]; !ok {
+		t.Fatalf("fresh readiness should include no_session_summary = %+v", freshReadiness)
+	}
+	if _, ok := freshReadiness["terminal_session_summary"]; ok {
+		t.Fatalf("fresh readiness should not include terminal_session_summary = %+v", freshReadiness)
+	}
+
+	sessionID := "rap-rw-adapter-session-d1d1d1d1d1d1d1d1d1d1d1d1"
+	delivery := RemoteWorkspaceFrameBatchDelivery{
+		ClusterID:         "cluster-1",
+		ChannelID:         "channel-rw",
+		ResourceID:        "workspace-exclusivity",
+		ServiceClass:      FabricServiceClassRemoteWorkspace,
+		ChannelClass:      FabricServiceChannelInteractive,
+		AdapterContractID: "rap.rdp_worker.remote_workspace_adapter_contract_probe.v1",
+		AdapterSessionID:  sessionID,
+		Frames: []RemoteWorkspaceFrameProbeRecord{{
+			Channel:   "display",
+			Direction: "adapter_to_client",
+			Droppable: true,
+		}},
+	}
+	if _, err := sink.AcceptRemoteWorkspaceFrameBatchProbe(context.Background(), delivery); err != nil {
+		t.Fatalf("accept frame batch: %v", err)
+	}
+	activeReport := sink.Report(time.Now().UTC())
+	activeReadiness, ok := activeReport["adapter_runtime_readiness"].(map[string]any)
+	if !ok {
+		t.Fatalf("active readiness missing from report = %+v", activeReport)
+	}
+	if activeReadiness["adapter_session_id"] != sessionID ||
+		activeReadiness["active_session_count"] != 1 {
+		t.Fatalf("invalid active readiness = %+v", activeReadiness)
+	}
+	if _, ok := activeReadiness["no_session_summary"]; ok {
+		t.Fatalf("active readiness should not include no_session_summary = %+v", activeReadiness)
+	}
+	if _, ok := activeReadiness["terminal_session_summary"]; ok {
+		t.Fatalf("active readiness should not include terminal_session_summary = %+v", activeReadiness)
+	}
+
+	server := httptest.NewServer(Server{RemoteWorkspaceFrameSink: sink}.Handler())
+	defer server.Close()
+	body := bytes.NewReader([]byte(`{"action":"close","reason":"unit summary exclusivity close"}`))
+	resp, err := http.Post(server.URL+"/mesh/v1/remote-workspace/adapter-sessions/"+sessionID+"/control", "application/json", body)
+	if err != nil {
+		t.Fatalf("post control: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		raw, _ := io.ReadAll(resp.Body)
+		t.Fatalf("status = %d body=%s", resp.StatusCode, string(raw))
+	}
+	terminalReport := sink.Report(time.Now().UTC())
+	terminalReadiness, ok := terminalReport["adapter_runtime_readiness"].(map[string]any)
+	if !ok {
+		t.Fatalf("terminal readiness missing from report = %+v", terminalReport)
+	}
+	if _, ok := terminalReadiness["terminal_session_summary"]; !ok {
+		t.Fatalf("terminal readiness should include terminal_session_summary = %+v", terminalReadiness)
+	}
+	if _, ok := terminalReadiness["no_session_summary"]; ok {
+		t.Fatalf("terminal readiness should not include no_session_summary = %+v", terminalReadiness)
+	}
+}
+
+func TestRemoteWorkspaceAdapterSessionControlTerminalReadinessStates(t *testing.T) {
+	tests := []struct {
+		action        string
+		sessionID     string
+		wantState     string
+		wantClosed    int64
+		wantExpired   int64
+		wantReset     int64
+		wantPrevState string
+	}{
+		{
+			action:        "expire",
+			sessionID:     "rap-rw-adapter-session-b0b0b0b0b0b0b0b0b0b0b0b0",
+			wantState:     "expired",
+			wantClosed:    1,
+			wantExpired:   1,
+			wantPrevState: "probe_bound",
+		},
+		{
+			action:        "reset",
+			sessionID:     "rap-rw-adapter-session-c0c0c0c0c0c0c0c0c0c0c0c0",
+			wantState:     "reset",
+			wantClosed:    1,
+			wantReset:     1,
+			wantPrevState: "probe_bound",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.action, func(t *testing.T) {
+			sink := NewRemoteWorkspaceFrameProbeSink()
+			delivery := RemoteWorkspaceFrameBatchDelivery{
+				ClusterID:         "cluster-1",
+				ChannelID:         "channel-rw",
+				ResourceID:        "workspace-" + tt.action,
+				ServiceClass:      FabricServiceClassRemoteWorkspace,
+				ChannelClass:      FabricServiceChannelInteractive,
+				AdapterContractID: "rap.rdp_worker.remote_workspace_adapter_contract_probe.v1",
+				AdapterSessionID:  tt.sessionID,
+				Frames: []RemoteWorkspaceFrameProbeRecord{{
+					Channel:   "display",
+					Direction: "adapter_to_client",
+					Droppable: true,
+				}},
+			}
+			if _, err := sink.AcceptRemoteWorkspaceFrameBatchProbe(context.Background(), delivery); err != nil {
+				t.Fatalf("accept frame batch: %v", err)
+			}
+			server := httptest.NewServer(Server{RemoteWorkspaceFrameSink: sink}.Handler())
+			defer server.Close()
+
+			body := bytes.NewReader([]byte(fmt.Sprintf(`{"action":%q,"reason":"unit terminal readiness"}`, tt.action)))
+			resp, err := http.Post(server.URL+"/mesh/v1/remote-workspace/adapter-sessions/"+tt.sessionID+"/control", "application/json", body)
+			if err != nil {
+				t.Fatalf("post control: %v", err)
+			}
+			defer resp.Body.Close()
+			if resp.StatusCode != http.StatusOK {
+				raw, _ := io.ReadAll(resp.Body)
+				t.Fatalf("status = %d body=%s", resp.StatusCode, string(raw))
+			}
+			var result RemoteWorkspaceAdapterSessionControlResult
+			if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+				t.Fatalf("decode control result: %v", err)
+			}
+			if !result.Accepted ||
+				result.Action != tt.action ||
+				result.AdapterSessionID != tt.sessionID ||
+				result.PreviousState != tt.wantPrevState ||
+				result.SessionState != tt.wantState ||
+				result.ActiveSessions != 0 {
+				t.Fatalf("control result = %+v", result)
+			}
+
+			report := sink.Report(time.Now().UTC())
+			if report["active_session_count"] != 0 ||
+				report["session_closed_total"] != tt.wantClosed ||
+				report["session_expired_total"] != tt.wantExpired ||
+				report["session_reset_total"] != tt.wantReset ||
+				report["last_controlled_adapter_session_id"] != tt.sessionID ||
+				report["last_session_control_action"] != tt.action ||
+				report["last_session_control_state"] != tt.wantState {
+				t.Fatalf("terminal control report = %+v", report)
+			}
+			readiness, ok := report["adapter_runtime_readiness"].(map[string]any)
+			if !ok {
+				t.Fatalf("adapter runtime readiness missing from report = %+v", report)
+			}
+			if readiness["status"] != "idle" ||
+				readiness["diagnostic_state"] != "last_session_terminal_or_expired" ||
+				readiness["ready"] != false ||
+				readiness["active_session_count"] != 0 ||
+				readiness["last_adapter_session_id"] != tt.sessionID ||
+				readiness["last_session_state"] != tt.wantState {
+				t.Fatalf("invalid terminal readiness = %+v", readiness)
+			}
+			if _, ok := readiness["adapter_session_id"]; ok {
+				t.Fatalf("adapter_session_id should be absent without active session = %+v", readiness)
+			}
+			if _, ok := readiness["last_preflight"]; ok {
+				t.Fatalf("last_preflight should be absent without active session = %+v", readiness)
+			}
+			if _, ok := readiness["no_session_summary"]; ok {
+				t.Fatalf("no_session_summary should be absent for terminal session history = %+v", readiness)
+			}
+			terminalSummary, ok := readiness["terminal_session_summary"].(map[string]any)
+			if !ok {
+				t.Fatalf("terminal session summary missing = %+v", readiness)
+			}
+			if terminalSummary["adapter_session_id"] != tt.sessionID ||
+				terminalSummary["schema_version"] != "rap.remote_workspace_adapter_terminal_session_summary.v1" ||
+				!stringAnySliceContains(terminalSummary["summary_contract"], "adapter_session_id") ||
+				!stringAnySliceContains(terminalSummary["summary_contract"], "session_state") ||
+				!stringAnySliceContains(terminalSummary["summary_contract"], "reason") ||
+				!stringAnySliceContains(terminalSummary["summary_contract"], "controlled_at") ||
+				!boolMapValue(terminalSummary["summary_features"], "adapter_session_id") ||
+				!boolMapValue(terminalSummary["summary_features"], "session_state") ||
+				!boolMapValue(terminalSummary["summary_features"], "reason") ||
+				!boolMapValue(terminalSummary["summary_features"], "controlled_at") ||
+				terminalSummary["session_state"] != tt.wantState ||
+				terminalSummary["reason"] != "unit terminal readiness" ||
+				terminalSummary["controlled_at"] == "" {
+				t.Fatalf("invalid terminal session summary = %+v", terminalSummary)
+			}
+		})
+	}
+}
+
 func TestRemoteWorkspaceAdapterSessionControlRejectsInvalidRequests(t *testing.T) {
 	sink := NewRemoteWorkspaceFrameProbeSink()
 	server := httptest.NewServer(Server{RemoteWorkspaceFrameSink: sink}.Handler())
@@ -3064,6 +3351,19 @@ func TestRemoteWorkspaceAdapterSessionMailboxPreflightIsReadOnly(t *testing.T) {
 	}
 	if preflight.ResumeFrom != "checkpoint" ||
 		preflight.ResumeSequence != 2 ||
+		preflight.DiagnosticState != "ready" ||
+		preflight.RecommendedAction != "resume_from_cursor" ||
+		preflight.ActionReason != "cursor_window_available" ||
+		preflight.OperatorSummary != "consumer cursor can resume from requested window" ||
+		preflight.OperatorStatus != "ready_to_resume" ||
+		preflight.OperatorSeverity != "ok" ||
+		anyInt64(preflight.ActionContext["resume_sequence"]) != 2 ||
+		anyInt64(preflight.ActionContext["first_retained_sequence"]) != 1 ||
+		preflight.OperatorSummaryFields["diagnostic_state"] != "ready" ||
+		preflight.OperatorSummaryFields["recommended_action"] != "resume_from_cursor" ||
+		preflight.OperatorSummaryFields["operator_status"] != "ready_to_resume" ||
+		preflight.OperatorSummaryFields["operator_severity"] != "ok" ||
+		!stringSliceContains(preflight.ActionHints, "resume_from_requested_cursor") ||
 		preflight.ExpectedAvailableCount != 1 ||
 		preflight.ExpectedReturnedCount != 1 ||
 		preflight.ExpectedSkippedCount != 2 ||
@@ -3079,6 +3379,547 @@ func TestRemoteWorkspaceAdapterSessionMailboxPreflightIsReadOnly(t *testing.T) {
 		reportAfter["current_session_mailbox_consumer_ack_total"] != reportBefore["current_session_mailbox_consumer_ack_total"] {
 		t.Fatalf("preflight mutated report before=%+v after=%+v", reportBefore, reportAfter)
 	}
+	if reportAfter["mailbox_preflight_total"] != int64(2) ||
+		reportAfter["mailbox_preflight_ack_total"] != int64(1) ||
+		reportAfter["mailbox_preflight_checkpoint_total"] != int64(1) ||
+		reportAfter["last_mailbox_preflight_adapter_session_id"] != sessionID ||
+		reportAfter["last_mailbox_preflight_consumer_id"] != "rdp-worker-probe" ||
+		reportAfter["last_mailbox_preflight_resume_from"] != "checkpoint" ||
+		reportAfter["last_mailbox_preflight_resume_sequence"] != int64(2) ||
+		reportAfter["last_mailbox_preflight_available_count"] != 1 ||
+		reportAfter["last_mailbox_preflight_returned_count"] != 1 ||
+		reportAfter["last_mailbox_preflight_skipped_count"] != 2 ||
+		reportAfter["current_session_mailbox_preflight_total"] != int64(2) ||
+		reportAfter["current_session_mailbox_preflight_ack_total"] != int64(1) ||
+		reportAfter["current_session_mailbox_preflight_checkpoint_total"] != int64(1) ||
+		mapInt64Value(reportAfter["current_session_mailbox_preflight_operator_status_counts"], "ready_to_resume") != 2 ||
+		mapInt64Value(reportAfter["current_session_mailbox_preflight_operator_severity_counts"], "ok") != 2 ||
+		reportAfter["current_session_last_mailbox_preflight_resume_from"] != "checkpoint" ||
+		reportAfter["current_session_last_mailbox_preflight_resume_sequence"] != int64(2) ||
+		reportAfter["current_session_last_mailbox_preflight_returned_count"] != 1 ||
+		reportAfter["current_session_last_mailbox_preflight_recommended_action"] != "resume_from_cursor" ||
+		reportAfter["last_mailbox_preflight_operator_summary"] != "consumer cursor can resume from requested window" ||
+		reportAfter["last_mailbox_preflight_operator_status"] != "ready_to_resume" ||
+		reportAfter["last_mailbox_preflight_operator_severity"] != "ok" ||
+		reportAfter["current_session_last_mailbox_preflight_operator_summary"] != "consumer cursor can resume from requested window" ||
+		reportAfter["current_session_last_mailbox_preflight_operator_status"] != "ready_to_resume" ||
+		reportAfter["current_session_last_mailbox_preflight_operator_severity"] != "ok" {
+		t.Fatalf("invalid preflight telemetry report = %+v", reportAfter)
+	}
+	readiness, ok := reportAfter["adapter_runtime_readiness"].(map[string]any)
+	if !ok {
+		t.Fatalf("adapter runtime readiness missing from report = %+v", reportAfter)
+	}
+	if readiness["mailbox_preflight_total"] != int64(2) ||
+		readiness["last_preflight_consumer_id"] != "rdp-worker-probe" ||
+		readiness["last_preflight_resume_from"] != "checkpoint" ||
+		readiness["last_preflight_resume_sequence"] != int64(2) ||
+		readiness["last_preflight_returned_count"] != 1 ||
+		readiness["last_preflight_skipped_count"] != 2 ||
+		readiness["last_preflight_recommended_action"] != "resume_from_cursor" ||
+		readiness["last_preflight_action_reason"] != "cursor_window_available" ||
+		readiness["last_preflight_operator_summary"] != "consumer cursor can resume from requested window" ||
+		readiness["last_preflight_operator_status"] != "ready_to_resume" ||
+		readiness["last_preflight_operator_severity"] != "ok" ||
+		mapInt64Value(readiness["mailbox_preflight_operator_status_counts"], "ready_to_resume") != 2 ||
+		mapInt64Value(readiness["mailbox_preflight_operator_severity_counts"], "ok") != 2 ||
+		readiness["preflight_attention_status"] != "clean" ||
+		readiness["preflight_attention_reason"] != "no_resync_required_preflight_observed" {
+		t.Fatalf("invalid preflight readiness = %+v", readiness)
+	}
+	lastPreflight, ok := readiness["last_preflight"].(map[string]any)
+	if !ok {
+		t.Fatalf("last preflight rollup missing from readiness = %+v", readiness)
+	}
+	if lastPreflight["consumer_id"] != "rdp-worker-probe" ||
+		lastPreflight["diagnostics_schema_version"] != "rap.remote_workspace_adapter_mailbox_preflight_diagnostics.v1" ||
+		!stringAnySliceContains(lastPreflight["diagnostics_contract"], "retained_window") ||
+		!stringAnySliceContains(lastPreflight["diagnostics_contract"], "remediation_checklist") ||
+		!stringAnySliceContains(lastPreflight["diagnostics_contract"], "attention") ||
+		!stringAnySliceContains(lastPreflight["diagnostics_contract"], "operator_counts") ||
+		!boolMapValue(lastPreflight["diagnostics_features"], "retained_window") ||
+		!boolMapValue(lastPreflight["diagnostics_features"], "remediation_checklist") ||
+		!boolMapValue(lastPreflight["diagnostics_features"], "attention") ||
+		!boolMapValue(lastPreflight["diagnostics_features"], "operator_counts") ||
+		lastPreflight["resume_from"] != "checkpoint" ||
+		lastPreflight["operator_status"] != "ready_to_resume" ||
+		lastPreflight["operator_severity"] != "ok" ||
+		lastPreflight["recommended_action"] != "resume_from_cursor" ||
+		!preflightChecklistContains(lastPreflight["remediation_checklist"], "resume_from_requested_cursor", true, true) ||
+		lastPreflight["remediation_checklist_status"] != "ready" ||
+		anyInt64(preflightChecklistCountsValue(lastPreflight["remediation_checklist_counts"], "required_count")) != 1 ||
+		anyInt64(preflightChecklistCountsValue(lastPreflight["remediation_checklist_counts"], "satisfied_count")) != 1 ||
+		anyInt64(preflightChecklistCountsValue(lastPreflight["remediation_checklist_counts"], "pending_count")) != 0 ||
+		mapInt64Value(lastPreflight["operator_status_counts"], "ready_to_resume") != 2 ||
+		mapInt64Value(lastPreflight["operator_severity_counts"], "ok") != 2 ||
+		lastPreflight["preflight_attention_status"] != "clean" ||
+		lastPreflight["preflight_attention_reason"] != "no_resync_required_preflight_observed" ||
+		anyInt64(lastPreflight["resume_sequence"]) != 2 ||
+		anyInt64(lastPreflight["first_retained_sequence"]) != 1 ||
+		anyInt64(lastPreflight["last_retained_sequence"]) != 3 ||
+		anyInt64(lastPreflight["mailbox_dropped_total"]) != 0 ||
+		anyInt64(lastPreflight["mailbox_preflight_total"]) != 2 {
+		t.Fatalf("invalid last preflight rollup = %+v", lastPreflight)
+	}
+}
+
+func TestRemoteWorkspaceAdapterSessionReadinessBeforePreflight(t *testing.T) {
+	sink := NewRemoteWorkspaceFrameProbeSink()
+	sessionID := "rap-rw-adapter-session-a0a0a0a0a0a0a0a0a0a0a0a0"
+	delivery := RemoteWorkspaceFrameBatchDelivery{
+		ClusterID:         "cluster-1",
+		ChannelID:         "channel-rw",
+		ResourceID:        "workspace-before-preflight",
+		ServiceClass:      FabricServiceClassRemoteWorkspace,
+		ChannelClass:      FabricServiceChannelInteractive,
+		AdapterContractID: "rap.rdp_worker.remote_workspace_adapter_contract_probe.v1",
+		AdapterSessionID:  sessionID,
+		Frames: []RemoteWorkspaceFrameProbeRecord{{
+			Channel:   "display",
+			Direction: "adapter_to_client",
+			Droppable: true,
+		}},
+	}
+	if _, err := sink.AcceptRemoteWorkspaceFrameBatchProbe(context.Background(), delivery); err != nil {
+		t.Fatalf("accept frame batch: %v", err)
+	}
+
+	report := sink.Report(time.Now().UTC())
+	if report["mailbox_preflight_total"] != int64(0) ||
+		report["current_session_mailbox_preflight_total"] != int64(0) {
+		t.Fatalf("unexpected preflight totals before preflight = %+v", report)
+	}
+	readiness, ok := report["adapter_runtime_readiness"].(map[string]any)
+	if !ok {
+		t.Fatalf("adapter runtime readiness missing from report = %+v", report)
+	}
+	if readiness["adapter_session_id"] != sessionID ||
+		readiness["mailbox_preflight_total"] != int64(0) ||
+		readiness["preflight_attention_status"] != "unknown" ||
+		readiness["preflight_attention_reason"] != "no_preflight_observed" {
+		t.Fatalf("invalid no-preflight readiness = %+v", readiness)
+	}
+	if _, ok := readiness["last_preflight"]; ok {
+		t.Fatalf("last preflight rollup should be absent before preflight = %+v", readiness["last_preflight"])
+	}
+	if readiness["last_preflight_diagnostic_state"] != "" ||
+		readiness["last_preflight_recommended_action"] != "" ||
+		len(readiness["last_preflight_action_hints"].([]string)) != 0 {
+		t.Fatalf("last preflight flat fields should be empty before preflight = %+v", readiness)
+	}
+}
+
+func TestRemoteWorkspaceAdapterSessionMailboxPreflightReportsStaleCursorGap(t *testing.T) {
+	sink := NewRemoteWorkspaceFrameProbeSink()
+	sessionID := "rap-rw-adapter-session-adadadadadadadadadadadad"
+	delivery := RemoteWorkspaceFrameBatchDelivery{
+		ClusterID:         "cluster-1",
+		ChannelID:         "channel-rw",
+		ResourceID:        "workspace-stale-0",
+		ServiceClass:      FabricServiceClassRemoteWorkspace,
+		ChannelClass:      FabricServiceChannelInteractive,
+		AdapterContractID: "rap.rdp_worker.remote_workspace_adapter_contract_probe.v1",
+		AdapterSessionID:  sessionID,
+		Frames: []RemoteWorkspaceFrameProbeRecord{{
+			Channel:   "display",
+			Direction: "adapter_to_client",
+			Droppable: true,
+		}},
+	}
+	if _, err := sink.AcceptRemoteWorkspaceFrameBatchProbe(context.Background(), delivery); err != nil {
+		t.Fatalf("accept initial frame batch: %v", err)
+	}
+	server := httptest.NewServer(Server{RemoteWorkspaceFrameSink: sink}.Handler())
+	defer server.Close()
+
+	resp, err := http.Get(server.URL + "/mesh/v1/remote-workspace/adapter-sessions/" + sessionID + "/mailbox?consumer_id=rdp-worker-probe&ack_sequence=1&limit=1")
+	if err != nil {
+		t.Fatalf("seed ack cursor: %v", err)
+	}
+	resp.Body.Close()
+	for i := 1; i <= DefaultRemoteWorkspaceAdapterMailboxCapacity+2; i++ {
+		delivery.ResourceID = fmt.Sprintf("workspace-stale-%d", i)
+		if _, err := sink.AcceptRemoteWorkspaceFrameBatchProbe(context.Background(), delivery); err != nil {
+			t.Fatalf("accept overflow frame batch %d: %v", i, err)
+		}
+	}
+
+	resp, err = http.Get(server.URL + "/mesh/v1/remote-workspace/adapter-sessions/" + sessionID + "/mailbox/preflight?consumer_id=rdp-worker-probe&resume_from=ack&limit=3")
+	if err != nil {
+		t.Fatalf("get stale preflight: %v", err)
+	}
+	defer resp.Body.Close()
+	var preflight RemoteWorkspaceAdapterMailboxPreflightSnapshot
+	if err := json.NewDecoder(resp.Body).Decode(&preflight); err != nil {
+		t.Fatalf("decode stale preflight: %v", err)
+	}
+	if preflight.ResumeFrom != "ack" ||
+		preflight.ResumeSequence != 1 ||
+		preflight.MailboxDepth != DefaultRemoteWorkspaceAdapterMailboxCapacity ||
+		preflight.MailboxDropped != 3 ||
+		preflight.ExpectedAvailableCount != DefaultRemoteWorkspaceAdapterMailboxCapacity ||
+		preflight.ExpectedReturnedCount != 3 ||
+		preflight.ExpectedSkippedCount != 0 ||
+		preflight.FirstExpectedSequence != 4 ||
+		preflight.LastExpectedSequence != 6 ||
+		preflight.FirstRetainedSequence != 4 ||
+		preflight.LastRetainedSequence != 19 ||
+		preflight.DiagnosticState != "stale_cursor_gap" ||
+		!preflight.StaleCursor ||
+		preflight.MissingDroppedCount != 2 ||
+		preflight.RecommendedAction != "reset_consumer_and_resync" ||
+		preflight.ActionReason != "consumer_cursor_before_first_retained_sequence" ||
+		preflight.OperatorSummary != "stale cursor gap: reset consumer and resync before resume" ||
+		preflight.OperatorStatus != "resync_required" ||
+		preflight.OperatorSeverity != "warn" ||
+		anyInt64(preflight.ActionContext["resume_sequence"]) != 1 ||
+		anyInt64(preflight.ActionContext["first_retained_sequence"]) != 4 ||
+		anyInt64(preflight.ActionContext["missing_dropped_count"]) != 2 ||
+		preflight.OperatorSummaryFields["diagnostic_state"] != "stale_cursor_gap" ||
+		preflight.OperatorSummaryFields["recommended_action"] != "reset_consumer_and_resync" ||
+		preflight.OperatorSummaryFields["operator_status"] != "resync_required" ||
+		preflight.OperatorSummaryFields["operator_severity"] != "warn" ||
+		anyInt64(preflight.OperatorSummaryFields["missing_dropped_count"]) != 2 ||
+		!stringSliceContains(preflight.ActionHints, "reset_consumer_cursor") ||
+		!stringSliceContains(preflight.ActionHints, "request_full_adapter_resync") ||
+		!stringSliceContains(preflight.ActionHints, "resume_from_checkpoint_after_resync") {
+		t.Fatalf("stale preflight = %+v", preflight)
+	}
+	resp, err = http.Get(server.URL + "/mesh/v1/remote-workspace/adapter-sessions/" + sessionID + "/mailbox/preflight?consumer_id=rdp-worker-probe&resume_from=ack&limit=3")
+	if err != nil {
+		t.Fatalf("get repeated stale preflight: %v", err)
+	}
+	resp.Body.Close()
+	report := sink.Report(time.Now().UTC())
+	if report["last_mailbox_preflight_diagnostic_state"] != "stale_cursor_gap" ||
+		report["last_mailbox_preflight_stale_cursor"] != true ||
+		report["last_mailbox_preflight_missing_dropped_count"] != 2 ||
+		report["last_mailbox_preflight_recommended_action"] != "reset_consumer_and_resync" ||
+		report["last_mailbox_preflight_action_reason"] != "consumer_cursor_before_first_retained_sequence" ||
+		report["last_mailbox_preflight_operator_summary"] != "stale cursor gap: reset consumer and resync before resume" ||
+		report["last_mailbox_preflight_operator_status"] != "resync_required" ||
+		report["last_mailbox_preflight_operator_severity"] != "warn" ||
+		report["current_session_last_mailbox_preflight_diagnostic_state"] != "stale_cursor_gap" ||
+		report["current_session_last_mailbox_preflight_stale_cursor"] != true ||
+		report["current_session_last_mailbox_preflight_missing_dropped_count"] != 2 ||
+		report["current_session_last_mailbox_preflight_recommended_action"] != "reset_consumer_and_resync" ||
+		report["current_session_last_mailbox_preflight_operator_summary"] != "stale cursor gap: reset consumer and resync before resume" ||
+		report["current_session_last_mailbox_preflight_operator_status"] != "resync_required" ||
+		report["current_session_last_mailbox_preflight_operator_severity"] != "warn" ||
+		mapInt64Value(report["current_session_mailbox_preflight_operator_status_counts"], "resync_required") != 2 ||
+		mapInt64Value(report["current_session_mailbox_preflight_operator_severity_counts"], "warn") != 2 {
+		t.Fatalf("stale preflight report = %+v", report)
+	}
+	readiness, ok := report["adapter_runtime_readiness"].(map[string]any)
+	if !ok {
+		t.Fatalf("adapter runtime readiness missing from report = %+v", report)
+	}
+	if readiness["last_preflight_diagnostic_state"] != "stale_cursor_gap" ||
+		readiness["last_preflight_stale_cursor"] != true ||
+		readiness["last_preflight_missing_dropped_count"] != 2 ||
+		readiness["last_preflight_recommended_action"] != "reset_consumer_and_resync" ||
+		readiness["last_preflight_action_reason"] != "consumer_cursor_before_first_retained_sequence" ||
+		readiness["last_preflight_operator_summary"] != "stale cursor gap: reset consumer and resync before resume" ||
+		readiness["last_preflight_operator_status"] != "resync_required" ||
+		readiness["last_preflight_operator_severity"] != "warn" ||
+		mapInt64Value(readiness["mailbox_preflight_operator_status_counts"], "resync_required") != 2 ||
+		mapInt64Value(readiness["mailbox_preflight_operator_severity_counts"], "warn") != 2 ||
+		readiness["preflight_attention_status"] != "repeated_resync_required" ||
+		readiness["preflight_attention_reason"] != "resync_required_preflight_repeated" {
+		t.Fatalf("stale preflight readiness = %+v", readiness)
+	}
+	lastPreflight, ok := readiness["last_preflight"].(map[string]any)
+	if !ok {
+		t.Fatalf("stale last preflight rollup missing from readiness = %+v", readiness)
+	}
+	if lastPreflight["diagnostic_state"] != "stale_cursor_gap" ||
+		lastPreflight["diagnostics_schema_version"] != "rap.remote_workspace_adapter_mailbox_preflight_diagnostics.v1" ||
+		!stringAnySliceContains(lastPreflight["diagnostics_contract"], "retained_window") ||
+		!stringAnySliceContains(lastPreflight["diagnostics_contract"], "remediation_checklist") ||
+		!stringAnySliceContains(lastPreflight["diagnostics_contract"], "attention") ||
+		!stringAnySliceContains(lastPreflight["diagnostics_contract"], "operator_counts") ||
+		!boolMapValue(lastPreflight["diagnostics_features"], "retained_window") ||
+		!boolMapValue(lastPreflight["diagnostics_features"], "remediation_checklist") ||
+		!boolMapValue(lastPreflight["diagnostics_features"], "attention") ||
+		!boolMapValue(lastPreflight["diagnostics_features"], "operator_counts") ||
+		lastPreflight["operator_status"] != "resync_required" ||
+		lastPreflight["operator_severity"] != "warn" ||
+		lastPreflight["recommended_action"] != "reset_consumer_and_resync" ||
+		lastPreflight["action_reason"] != "consumer_cursor_before_first_retained_sequence" ||
+		!preflightChecklistContains(lastPreflight["remediation_checklist"], "reset_consumer_cursor", true, false) ||
+		!preflightChecklistContains(lastPreflight["remediation_checklist"], "request_full_adapter_resync", true, false) ||
+		!preflightChecklistContains(lastPreflight["remediation_checklist"], "resume_from_checkpoint_after_resync", true, false) ||
+		lastPreflight["remediation_checklist_status"] != "action_required" ||
+		anyInt64(preflightChecklistCountsValue(lastPreflight["remediation_checklist_counts"], "required_count")) != 3 ||
+		anyInt64(preflightChecklistCountsValue(lastPreflight["remediation_checklist_counts"], "satisfied_count")) != 0 ||
+		anyInt64(preflightChecklistCountsValue(lastPreflight["remediation_checklist_counts"], "pending_count")) != 3 ||
+		mapInt64Value(lastPreflight["operator_status_counts"], "resync_required") != 2 ||
+		mapInt64Value(lastPreflight["operator_severity_counts"], "warn") != 2 ||
+		lastPreflight["preflight_attention_status"] != "repeated_resync_required" ||
+		lastPreflight["preflight_attention_reason"] != "resync_required_preflight_repeated" ||
+		anyInt64(lastPreflight["missing_dropped_count"]) != 2 ||
+		anyInt64(lastPreflight["first_retained_sequence"]) != 4 ||
+		anyInt64(lastPreflight["last_retained_sequence"]) != 19 ||
+		anyInt64(lastPreflight["mailbox_dropped_total"]) != 3 ||
+		anyInt64(lastPreflight["resume_sequence"]) != 1 {
+		t.Fatalf("invalid stale last preflight rollup = %+v", lastPreflight)
+	}
+}
+
+func preflightChecklistCountsValue(value any, key string) any {
+	switch counts := value.(type) {
+	case map[string]any:
+		return counts[key]
+	default:
+		return nil
+	}
+}
+
+func mapInt64Value(value any, key string) int64 {
+	switch items := value.(type) {
+	case map[string]int64:
+		return items[key]
+	case map[string]any:
+		return anyInt64(items[key])
+	default:
+		return 0
+	}
+}
+
+func boolMapValue(value any, key string) bool {
+	switch items := value.(type) {
+	case map[string]bool:
+		return items[key]
+	case map[string]any:
+		item, _ := items[key].(bool)
+		return item
+	default:
+		return false
+	}
+}
+
+func preflightDiagnosticsContractCompatible(rollup map[string]any) bool {
+	for _, feature := range []string{"retained_window", "remediation_checklist", "attention", "operator_counts"} {
+		if !stringAnySliceContains(rollup["diagnostics_contract"], feature) || !boolMapValue(rollup["diagnostics_features"], feature) {
+			return false
+		}
+	}
+	return true
+}
+
+func terminalSessionSummaryContractCompatible(summary map[string]any) bool {
+	for _, feature := range []string{"adapter_session_id", "session_state", "reason", "controlled_at"} {
+		if !stringAnySliceContains(summary["summary_contract"], feature) || !boolMapValue(summary["summary_features"], feature) {
+			return false
+		}
+	}
+	return true
+}
+
+func noSessionSummaryContractCompatible(summary map[string]any) bool {
+	for _, feature := range []string{"status", "diagnostic_state", "active_session_count", "terminal_session_count"} {
+		if !stringAnySliceContains(summary["summary_contract"], feature) || !boolMapValue(summary["summary_features"], feature) {
+			return false
+		}
+	}
+	return true
+}
+
+func stringAnySliceContains(value any, want string) bool {
+	switch items := value.(type) {
+	case []string:
+		for _, item := range items {
+			if item == want {
+				return true
+			}
+		}
+	case []any:
+		for _, item := range items {
+			if item == want {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func preflightChecklistContains(value any, step string, required bool, satisfied bool) bool {
+	switch items := value.(type) {
+	case []map[string]any:
+		for _, item := range items {
+			if item["step"] == step && item["required"] == required && item["satisfied"] == satisfied && item["source_hint"] == true {
+				return true
+			}
+		}
+	case []any:
+		for _, raw := range items {
+			item, ok := raw.(map[string]any)
+			if !ok {
+				continue
+			}
+			if item["step"] == step && item["required"] == required && item["satisfied"] == satisfied && item["source_hint"] == true {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func stringSliceContains(items []string, want string) bool {
+	for _, item := range items {
+		if item == want {
+			return true
+		}
+	}
+	return false
+}
+
+func anyInt64(value any) int64 {
+	switch v := value.(type) {
+	case int:
+		return int64(v)
+	case int64:
+		return v
+	case float64:
+		return int64(v)
+	default:
+		return 0
+	}
+}
+
+func TestRemoteWorkspacePreflightDiagnosticsContractCompatibility(t *testing.T) {
+	compatible := map[string]any{
+		"diagnostics_contract": []string{"retained_window", "remediation_checklist", "attention", "operator_counts"},
+		"diagnostics_features": map[string]bool{"retained_window": true, "remediation_checklist": true, "attention": true, "operator_counts": true},
+	}
+	if !preflightDiagnosticsContractCompatible(compatible) {
+		t.Fatalf("expected contract/features to be compatible")
+	}
+
+	tests := []struct {
+		name   string
+		rollup map[string]any
+	}{
+		{
+			name: "missing contract item",
+			rollup: map[string]any{
+				"diagnostics_contract": []string{"retained_window", "remediation_checklist", "attention"},
+				"diagnostics_features": map[string]bool{"retained_window": true, "remediation_checklist": true, "attention": true, "operator_counts": true},
+			},
+		},
+		{
+			name: "missing feature flag",
+			rollup: map[string]any{
+				"diagnostics_contract": []string{"retained_window", "remediation_checklist", "attention", "operator_counts"},
+				"diagnostics_features": map[string]bool{"retained_window": true, "remediation_checklist": true, "attention": true},
+			},
+		},
+		{
+			name: "false feature flag",
+			rollup: map[string]any{
+				"diagnostics_contract": []string{"retained_window", "remediation_checklist", "attention", "operator_counts"},
+				"diagnostics_features": map[string]bool{"retained_window": true, "remediation_checklist": true, "attention": true, "operator_counts": false},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if preflightDiagnosticsContractCompatible(tt.rollup) {
+				t.Fatalf("expected incompatible contract/features for %+v", tt.rollup)
+			}
+		})
+	}
+}
+
+func TestRemoteWorkspaceTerminalSessionSummaryContractCompatibility(t *testing.T) {
+	compatible := map[string]any{
+		"summary_contract": []string{"adapter_session_id", "session_state", "reason", "controlled_at"},
+		"summary_features": map[string]bool{"adapter_session_id": true, "session_state": true, "reason": true, "controlled_at": true},
+	}
+	if !terminalSessionSummaryContractCompatible(compatible) {
+		t.Fatalf("expected summary contract/features to be compatible")
+	}
+
+	tests := []struct {
+		name    string
+		summary map[string]any
+	}{
+		{
+			name: "missing contract item",
+			summary: map[string]any{
+				"summary_contract": []string{"adapter_session_id", "session_state", "reason"},
+				"summary_features": map[string]bool{"adapter_session_id": true, "session_state": true, "reason": true, "controlled_at": true},
+			},
+		},
+		{
+			name: "missing feature flag",
+			summary: map[string]any{
+				"summary_contract": []string{"adapter_session_id", "session_state", "reason", "controlled_at"},
+				"summary_features": map[string]bool{"adapter_session_id": true, "session_state": true, "reason": true},
+			},
+		},
+		{
+			name: "false feature flag",
+			summary: map[string]any{
+				"summary_contract": []string{"adapter_session_id", "session_state", "reason", "controlled_at"},
+				"summary_features": map[string]bool{"adapter_session_id": true, "session_state": true, "reason": true, "controlled_at": false},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if terminalSessionSummaryContractCompatible(tt.summary) {
+				t.Fatalf("expected incompatible summary contract/features for %+v", tt.summary)
+			}
+		})
+	}
+}
+
+func TestRemoteWorkspaceNoSessionSummaryContractCompatibility(t *testing.T) {
+	compatible := map[string]any{
+		"summary_contract": []string{"status", "diagnostic_state", "active_session_count", "terminal_session_count"},
+		"summary_features": map[string]bool{"status": true, "diagnostic_state": true, "active_session_count": true, "terminal_session_count": true},
+	}
+	if !noSessionSummaryContractCompatible(compatible) {
+		t.Fatalf("expected no-session summary contract/features to be compatible")
+	}
+
+	tests := []struct {
+		name    string
+		summary map[string]any
+	}{
+		{
+			name: "missing contract item",
+			summary: map[string]any{
+				"summary_contract": []string{"status", "diagnostic_state", "active_session_count"},
+				"summary_features": map[string]bool{"status": true, "diagnostic_state": true, "active_session_count": true, "terminal_session_count": true},
+			},
+		},
+		{
+			name: "missing feature flag",
+			summary: map[string]any{
+				"summary_contract": []string{"status", "diagnostic_state", "active_session_count", "terminal_session_count"},
+				"summary_features": map[string]bool{"status": true, "diagnostic_state": true, "active_session_count": true},
+			},
+		},
+		{
+			name: "false feature flag",
+			summary: map[string]any{
+				"summary_contract": []string{"status", "diagnostic_state", "active_session_count", "terminal_session_count"},
+				"summary_features": map[string]bool{"status": true, "diagnostic_state": true, "active_session_count": true, "terminal_session_count": false},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if noSessionSummaryContractCompatible(tt.summary) {
+				t.Fatalf("expected incompatible no-session summary contract/features for %+v", tt.summary)
+			}
+		})
+	}
 }
 
 func TestRemoteWorkspaceAdapterSessionMailboxPreflightRejectsInvalidRequests(t *testing.T) {
@@ -3145,6 +3986,57 @@ func TestRemoteWorkspaceAdapterSessionMailboxPreflightRejectsInvalidRequests(t *
 	}
 }
 
+func TestRemoteWorkspacePreflightAttentionReasonSummaries(t *testing.T) {
+	tests := []struct {
+		name           string
+		statusCounts   map[string]int64
+		severityCounts map[string]int64
+		wantStatus     string
+		wantReason     string
+	}{
+		{
+			name:           "clean ready",
+			statusCounts:   map[string]int64{"ready_to_resume": 1},
+			severityCounts: map[string]int64{"ok": 1},
+			wantStatus:     "clean",
+			wantReason:     "no_resync_required_preflight_observed",
+		},
+		{
+			name:           "single resync",
+			statusCounts:   map[string]int64{"resync_required": 1},
+			severityCounts: map[string]int64{"warn": 1},
+			wantStatus:     "needs_attention",
+			wantReason:     "resync_required_preflight_observed",
+		},
+		{
+			name:           "repeated resync",
+			statusCounts:   map[string]int64{"resync_required": 2},
+			severityCounts: map[string]int64{"warn": 2},
+			wantStatus:     "repeated_resync_required",
+			wantReason:     "resync_required_preflight_repeated",
+		},
+		{
+			name:           "none observed",
+			statusCounts:   map[string]int64{},
+			severityCounts: map[string]int64{},
+			wantStatus:     "unknown",
+			wantReason:     "no_preflight_observed",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			status := remoteWorkspacePreflightAttentionStatus(tt.statusCounts, tt.severityCounts)
+			if status != tt.wantStatus {
+				t.Fatalf("status=%q want %q", status, tt.wantStatus)
+			}
+			reason := remoteWorkspacePreflightAttentionReason(status, tt.statusCounts, tt.severityCounts)
+			if reason != tt.wantReason {
+				t.Fatalf("reason=%q want %q", reason, tt.wantReason)
+			}
+		})
+	}
+}
+
 func TestFabricServiceChannelVPNPacketIngressHonorsDisabledBackendRelayPolicy(t *testing.T) {
 	publicKey, privateKey, err := ed25519.GenerateKey(nil)
 	if err != nil {