chore: branches polish — global-leak docs + unknown-name warning (T103)

tests/test_branches_state.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import logging
+
 from chat.db.connection import open_db
 from chat.db.migrate import apply_migrations
 from chat.eventlog.log import append_event
@@ -139,3 +141,36 @@ def test_list_branches_returns_all(tmp_path):
         names = [b["name"] for b in list_branches(conn)]
         assert "main" in names
         assert "experiment" in names
+
+
+def test_branch_switched_unknown_name_warns(tmp_path, caplog):
+    """Switching to a nonexistent branch logs a warning and leaves no branch active.
+
+    The previous behavior silently cleared is_active flags and applied no UPDATE
+    when the named branch did not exist. T103 makes that condition observable
+    by emitting a warning while preserving the existing (zero-active) outcome.
+    """
+    db = tmp_path / "t.db"
+    apply_migrations(db)
+    with open_db(db) as conn:
+        with caplog.at_level(logging.WARNING, logger="chat.state.branches"):
+            append_event(
+                conn,
+                kind="branch_switched",
+                payload={"name": "does_not_exist"},
+            )
+            project(conn)
+
+        # A warning was emitted naming the missing branch.
+        warnings = [
+            r for r in caplog.records
+            if r.levelno == logging.WARNING and r.name == "chat.state.branches"
+        ]
+        assert warnings, "expected a warning for unknown branch name"
+        assert any("does_not_exist" in r.getMessage() for r in warnings)
+
+        # Existing behavior preserved: no branch is active after the switch.
+        assert active_branch(conn) is None
+
+        # The unknown name was not inserted as a side effect.
+        assert get_branch(conn, "does_not_exist") is None