feat: cap pinned sessions from sidebar

[Michaelyklam]

Thinking Path

• Issue 会话里的对话内容 能提供置顶功能吗 #2508 clarified the requested first slice as session-level pinning from the sidebar, not message-level pins.
• The WebUI already had a session pinned group and action-menu pin toggle, so the safest slice is to complete the requested workflow rather than introduce a parallel pinned-items surface.
• The missing pieces were right-click access to the action menu and the requested three-pinned-session cap.
• The cap needs to live in the backend as the source of truth, with a frontend guard only for clearer UX.

What Changed

• Adds a backend guard to /api/session/pin that rejects a fourth active pinned conversation until one is unpinned.
• Adds a frontend pinned-count guard and muted disabled menu styling for the pin action when the cap is reached.
• Opens the existing session action menu from a right-click/context-menu gesture on session rows.
• Adds regression coverage for the backend cap, frontend/source guard, disabled styling, and right-click menu hook.
• Adds an Unreleased changelog entry.

Why It Matters

• Matches the clarified 会话里的对话内容 能提供置顶功能吗 #2508 workflow: right-click a conversation, pin it, keep frequently used conversations in the pinned bucket, and keep the pinned area bounded.
• Keeps pin state on the existing session model so it persists across reloads and devices through server-side session state.
• Avoids a broad sidebar redesign or a duplicate pinning system.

Verification

• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_issue2508_session_pin_cap.py tests/test_sprint12.py::test_pin_session tests/test_sprint12.py::test_unpin_session tests/test_sprint12.py::test_pinned_in_session_list tests/test_issue856_pinned_indicator_layout.py -q — 15 passed
• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m py_compile api/routes.py
• node --check static/sessions.js
• git diff --check
• Raw screenshot media verified HTTP 200.

UI Media

Risks / Follow-ups

• This preserves the existing pinned group at the top of the sidebar rather than adding a new right-side panel. The reporter's mockup/comment described both a right-click workflow and display near the top/right; this PR keeps the change bounded to the existing sidebar architecture.
• The cap ignores archived sessions so users can archive old pinned conversations without having them consume one of the three active pin slots.

Refs #2508

Model Used

AI-assisted change with repository inspection, targeted editing, and shell-based test verification.

[nesquena-hermes]

Summary

Reviewed the diff at cron-pr-2614 against origin/master. The PR adds a 3-pin cap with a backend guard, frontend optimistic check, disabled-menu styling, and a right-click context-menu entry point — all four items the original reporter explicitly requested on #2508. CI is green on 3.11/3.12/3.13.

Backend cap

api/routes.py:5631-5650 (post-fix):

pin_requested = bool(body.get("pinned", True))
if pin_requested and not getattr(s, "pinned", False):
    pinned_ids = {
        getattr(existing, "session_id", None) for existing in all_sessions()
        if getattr(existing, "pinned", False) and not getattr(existing, "archived", False)
    }
    with LOCK:
        pinned_ids.update(
            sid for sid, existing in SESSIONS.items()
            if getattr(existing, "pinned", False) and not getattr(existing, "archived", False)
        )
    pinned_ids.discard(body["session_id"])
    if len(pinned_ids) >= 3:
        return bad(handler, "Up to 3 sessions can be pinned. ...", 400)

Two things to flag:

1. all_sessions() is the right source. It already returns compact() dicts and the sort path at api/models.py:1655 ordered by (pinned, sort_ts). The compact dict at api/models.py:670-673 includes both pinned and archived, so the comprehension works. Good.

2. The with LOCK overlay is necessary but subtle. all_sessions() overlays SESSIONS itself inside its own with LOCK block (api/models.py:1598-1603), so doing it again here is a belt-and-braces guard. It does ensure that an in-memory session not yet present in the index is still counted — defensive, no race against a concurrent pin call other than the LOCK serialising the read. Not wrong, but worth noting that the overlap means the comprehension runs the lock check twice on the same iteration. Cheap enough not to matter; the alternative (read inside all_sessions() only) would still be correct.

3. Toggle-off has no guard, which is correct. Unpinning is always allowed, so a user who pinned a fourth session via a stale client can recover by unpinning rather than being deadlocked.

Frontend guards

static/sessions.js:1788-1810:

const pinLimitReached=!session.pinned&&_pinnedSessionCount()>=3;
menu.appendChild(_buildSessionAction(
  session.pinned?t('session_unpin'):t('session_pin'),
  pinLimitReached?'Only 3 conversations can be pinned':(session.pinned?t('session_unpin_desc'):t('session_pin_desc')),
  ...
  async()=>{
    closeSessionActionMenu();
    if(pinLimitReached){
      if(typeof showToast==='function') showToast('Only 3 conversations can be pinned. Unpin one before pinning another.',3000,'error');
      return;
    }
    ...
  },
  (session.pinned?'is-active':'')+(pinLimitReached?' is-disabled':'')
));

_pinnedSessionCount() at static/sessions.js:1478-1480 reads from _allSessions (the sidebar cache), so the count reflects what the user is looking at. If the cache is stale, the backend guard at api/routes.py:5647 still rejects the pin and returns 400. That's the right pattern — optimistic UI + authoritative server.

Right-click handler

static/sessions.js:3399-3408:

el.oncontextmenu=(e)=>{
  if(readOnly) return;
  e.preventDefault();
  e.stopPropagation();
  ...
  _openSessionActionMenu(s, actions||el);
};

The readOnly short-circuit is consistent with how the existing … action button is conditionally hidden — read-only sessions don't get the action affordance at all. clearTimeout(_tapTimer); _tapTimer=null; _lastTapTime=0; _clearPointerDragState(); resets touch-double-tap state, which avoids the right-click + accidental-double-tap interaction described in the touch-device fallback comments later in the file. Solid.

Test coverage

tests/test_issue2508_session_pin_cap.py:42-66 runs against BASE (the pytest port) and exercises the actual HTTP endpoint, including the 400-on-4th-pin and the "unpin one to free a slot" workflow. The non-HTTP test_session_pin_cap_has_backend_and_frontend_guards and test_session_rows_open_action_menu_from_right_click are source-string snapshots — slightly brittle, but they guard against accidental removal of the cap check or the right-click handler in future refactors. Acceptable.

Recommendation

LGTM. Two nits worth considering for follow-up (not blocking):

• The cap message uses both "Up to 3 sessions can be pinned" (backend) and "Only 3 conversations can be pinned" (frontend toast). Worth aligning the wording in a future polish pass.
• The hard-coded 3 appears in api/routes.py:5647, static/sessions.js:1789, and the test. A MAX_PINNED_SESSIONS constant on the backend exposed via a small config or response field would let the frontend stay in sync if this is ever bumped to 5 or 10. Not worth blocking this PR over.