feat(sessions): workspace_key grouping helper + tests

A session's coarse workspace identity: its git repo root when known, else its
cwd (branch excluded, so switching branches doesn't fragment history). Pure
helper over fields sessions already record — no new columns, no git shelling.

Co-authored-by: Cary Palmer <palmer@dugoutfantasy.com>

hermes_state.py

@@ -31,6 +31,24 @@ from typing import Any, Callable, Dict, List, Optional, Tuple, TypeVar
 
 logger = logging.getLogger(__name__)
 
+
+def workspace_key(row: Dict[str, Any]) -> Optional[str]:
+    """A session's workspace grouping key: its git repo root when known, else
+    its cwd.
+
+    Branch is deliberately excluded so checking out a new branch doesn't
+    fragment a workspace's session history. Returns None for cwd-less (unbound)
+    sessions. Both fields are already recorded on ``sessions`` — this just picks
+    the coarser identity for grouping/filtering.
+    """
+    root = (row.get("git_repo_root") or "").strip()
+    if root:
+        return root
+
+    cwd = (row.get("cwd") or "").strip()
+    return cwd or None
+
+
 def _delegate_from_json(col: str = "model_config") -> str:
     return f"json_extract(COALESCE({col}, '{{}}'), '$._delegate_from')"
 

tests/test_session_workspace_binding.py

@@ -0,0 +1,38 @@
+"""Session <-> workspace grouping key (hermes_state.workspace_key).
+
+The key is what `hermes sessions list --workspace` groups/filters on. It is a
+coarse workspace identity derived from fields already recorded on sessions
+(git_repo_root, cwd) — no git shelling, no new columns. Branch is deliberately
+NOT part of the key.
+"""
+
+from hermes_state import workspace_key
+
+
+def test_repo_root_is_the_key_when_known():
+    row = {"git_repo_root": "/www/app", "cwd": "/www/app/src", "git_branch": "feat"}
+    assert workspace_key(row) == "/www/app"
+
+
+def test_falls_back_to_cwd_for_non_git_sessions():
+    assert workspace_key({"cwd": "/work/notes"}) == "/work/notes"
+    assert workspace_key({"git_repo_root": "", "cwd": "/work/notes"}) == "/work/notes"
+
+
+def test_none_when_unbound():
+    assert workspace_key({}) is None
+    assert workspace_key({"cwd": "", "git_repo_root": ""}) is None
+    assert workspace_key({"cwd": "   "}) is None
+
+
+def test_branch_does_not_affect_the_key():
+    # Two sessions on the same repo, different branches, group together.
+    a = {"git_repo_root": "/www/app", "git_branch": "main"}
+    b = {"git_repo_root": "/www/app", "git_branch": "feature-x"}
+    assert workspace_key(a) == workspace_key(b) == "/www/app"
+
+
+def test_repo_root_wins_over_a_differing_cwd():
+    # A worktree/subdir session still groups under its repo root, not its cwd.
+    row = {"git_repo_root": "/www/app", "cwd": "/www/app/.worktrees/x"}
+    assert workspace_key(row) == "/www/app"