feat(history,gateway): D4 会话未读/已读游标 — unreadCount + POST /sessions/{id}/read + session_read 广播

- chat_sessions 增 read_at（毫秒，与 chat_messages.created_at 同单位）；迁移 0010 并把既有会话回填为各自最新消息时间（升级当天不误报）
- ListSessions 单查询派生 unreadCount（无 N+1，复用 idx_chat_msgs_session_created 覆盖索引）
- MarkSessionRead 只前进 MAX(read_at, ?)；未知会话 ErrSessionNotFound；游标方法挂在网关消费侧窄接口（沿用 GetMessage/messageLookup 先例，避免污染 runtime 接口与其 fake）
- POST /api/v1/sessions/{id}/read：writeAuth + 400/404/501，成功广播 session_read、失败路径不广播
- Docs/api-client v0.37（§1 unreadCount / 新行 8a / §3.9 session_read / §4.2 用法）
- 含迁移回填测试、store/handler 测试与变异验证；顺带把 migrate_pinned_test 的「回退一步=0009」硬编码改为对迁移数量免疫

internal/runtime/history/session_preview.go

@@ -7,11 +7,12 @@ import (
 	"strings"
 )
 
-// This file owns the last-message preview carried in the session list
-// (GET /api/v1/sessions): a display-only summary of each session's newest message so a
-// client can render a conversation row without one request per session. The preview is
-// truncated for display and never feeds identity or permission decisions — identity
-// comes from channel actor metadata / JWT (project red line).
+// This file owns the two derived per-session display fields carried in the session
+// list (GET /api/v1/sessions): the last-message preview and the unread count. Both are
+// read-only projections so a client can render a conversation row (with its unread
+// badge) without one request per session. The preview is truncated for display, and
+// neither field ever feeds identity or permission decisions — identity comes from
+// channel actor metadata / JWT (project red line).
 
 // lastMessagePreviewRunes bounds the preview content so a long message cannot bloat the
 // session-list response. A longer message is whitespace-collapsed and truncated to this
@@ -25,14 +26,19 @@ type MessageSummary struct {
 	CreatedAt int64  // Unix milliseconds
 }
 
-// listSessionsQuery reads every session plus its newest message in one statement. The
-// LEFT JOIN's correlated subquery resolves each session's newest row via the
-// (session_id, created_at DESC) index (rowid DESC breaks a same-millisecond tie by
-// insertion order), so a session with no messages still appears with NULL preview
-// columns. Ordering floats pinned sessions first, then keeps the main session before
-// unpinned subs, then subs oldest-first.
+// listSessionsQuery reads every session plus its newest message and its unread count
+// in one statement. The LEFT JOIN's correlated subquery resolves each session's newest
+// row via the (session_id, created_at DESC) index (rowid DESC breaks a same-millisecond
+// tie by insertion order), so a session with no messages still appears with NULL preview
+// columns. The unread count is a correlated COUNT(*) over the same index
+// (session_id = s.id AND created_at > s.read_at is an equality + range scan), so no
+// per-session round trip (N+1) is needed and no extra index is required. Ordering floats
+// pinned sessions first, then keeps the main session before unpinned subs, then subs
+// oldest-first.
 const listSessionsQuery = `SELECT s.id, s.type, s.title, s.pinned, s.created_at,
-		m.role, m.content, m.created_at
+		m.role, m.content, m.created_at,
+		(SELECT COUNT(*) FROM chat_messages c
+			WHERE c.session_id = s.id AND c.created_at > s.read_at)
 	FROM chat_sessions s
 	LEFT JOIN chat_messages m ON m.rowid = (
 		SELECT rowid FROM chat_messages
@@ -44,8 +50,9 @@ const listSessionsQuery = `SELECT s.id, s.type, s.title, s.pinned, s.created_at,
 
 // ListSessions returns pinned sessions first, then the main session, then every sub
 // session, oldest first, each carrying a LastMessage preview of its newest message (nil
-// when the session has none). Sessions and previews are read in a single query, so the
-// query count does not grow with the number of sessions. The returned slice is non-nil.
+// when the session has none) and the UnreadCount derived from the session's read cursor.
+// Sessions, previews and unread counts are read in a single query, so the query count
+// does not grow with the number of sessions. The returned slice is non-nil.
 func (s *Store) ListSessions(ctx context.Context) ([]SessionMeta, error) {
 	rows, err := s.db.QueryContext(ctx, listSessionsQuery, SessionMain)
 	if err != nil {
@@ -67,9 +74,10 @@ func (s *Store) ListSessions(ctx context.Context) ([]SessionMeta, error) {
 	return sessions, nil
 }
 
-// scanSessionMeta reads one joined chat_sessions + last-message row. The three message
-// columns are NULL for a session that has never received a message, so they scan into
-// nullable holders and only produce a LastMessage when a row is present.
+// scanSessionMeta reads one joined chat_sessions + last-message + unread-count row. The
+// three message columns are NULL for a session that has never received a message, so they
+// scan into nullable holders and only produce a LastMessage when a row is present. The
+// unread count is a non-NULL COUNT(*), so it scans into a plain int.
 func scanSessionMeta(sc rowScanner) (SessionMeta, error) {
 	var (
 		meta    SessionMeta
@@ -79,7 +87,7 @@ func scanSessionMeta(sc rowScanner) (SessionMeta, error) {
 		content sql.NullString
 		lastAt  sql.NullInt64
 	)
-	if err := sc.Scan(&meta.ID, &typeStr, &meta.Title, &pinned, &meta.CreatedAt, &role, &content, &lastAt); err != nil {
+	if err := sc.Scan(&meta.ID, &typeStr, &meta.Title, &pinned, &meta.CreatedAt, &role, &content, &lastAt, &meta.UnreadCount); err != nil {
 		return SessionMeta{}, err
 	}
 	meta.Type = typeStr