diff --git a/src/crud/session.py b/src/crud/session.py
index 1cb0a06a..707e5ceb 100644
--- a/src/crud/session.py
+++ b/src/crud/session.py
@@ -1050,14 +1050,16 @@ async def set_peers_for_session(
     peer_names: dict[str, schemas.SessionPeerConfig],
 ) -> list[models.SessionPeer]:
     """
-    Set peers for a session, overwriting any existing peers.
-    If peers don't exist, they will be created.
+    Replace a session's ordinary peer set with ``peer_names``.
+
+    Active members keep their joined_at and configuration. Departed members
+    rejoin with the incoming configuration. Scope memberships are preserved.
 
     Args:
         db: Database session
         workspace_name: Name of the workspace
         session_name: Name of the session
-        peer_names: Set of peer names to set for the session
+        peer_names: Mapping of peer names to session-level configuration
 
     Returns:
         List of SessionPeer objects for all peers in the session
diff --git a/tests/crud/test_session.py b/tests/crud/test_session.py
index 8427622a..bcc3f089 100644
--- a/tests/crud/test_session.py
+++ b/tests/crud/test_session.py
@@ -18,7 +18,8 @@ class TestSessionCRUD:
         db_session: AsyncSession,
         sample_data: tuple[models.Workspace, models.Peer],
     ):
-        """Active re-adds keep joined_at and config; a genuine rejoin starts a new window."""
+        """Active re-adds keep joined_at and config; a genuine rejoin starts a
+        new window."""
         test_workspace, test_peer = sample_data
         session_name = str(generate_nanoid())
         original_config = schemas.SessionPeerConfig(
diff --git a/tests/test_search.py b/tests/test_search.py
index 4ad0559f..b4b69c43 100644
--- a/tests/test_search.py
+++ b/tests/test_search.py
@@ -711,7 +711,8 @@ async def test_grep_messages_observer_scoping_left_session_still_visible(
 async def test_peer_perspective_search_after_active_readd(
     db_session: AsyncSession,
 ):
-    """Active re-add keeps existing messages visible; a genuine rejoin starts a new window."""
+    """Active re-add keeps existing messages visible; a genuine rejoin starts a
+    new window."""
     workspace = models.Workspace(name=generate_nanoid())
     peer1 = models.Peer(name="peer1", workspace_name=workspace.name)
     peer2 = models.Peer(name="peer2", workspace_name=workspace.name)