diff --git a/internal/session/session.go b/internal/session/session.go
index 0271bf9a293095c259f114bce2de5e0d901e5ec1..8c13d2f146993909ff6f31417ed3fda4206def74 100644
--- a/internal/session/session.go
+++ b/internal/session/session.go
@@ -322,6 +322,11 @@ func (s *service) UpdateSessionModels(ctx context.Context, id string, models map
 	return err
 }
 
+// SaveWithModels saves the session and then persists the models column as a
+// second operation. This is intentionally non-atomic: if the models update
+// fails, the session fields are still saved (which is equivalent to the
+// pre-feature behavior where models were never persisted). The next agent turn
+// will retry the models write, so transient failures are self-healing.
 func (s *service) SaveWithModels(ctx context.Context, session Session, models map[config.SelectedModelType]config.SelectedModel) (Session, error) {
 	saved, err := s.Save(ctx, session)
 	if err != nil {