feat(web): rich hover tooltips on session-list attention indicators

The session-row attention dots and the future-scheduled clock icon used
plain `title=""` attributes which gave only a one-word label ("Permission
required"). Replace those with hover/focus-revealed tooltips that name
*which* tools are blocking, count background tasks, surface the
"updated Nm ago" timestamp, and explain the pending schedule.

To make per-tool copy possible without an extra round trip,
`SessionSummary` now carries a structured slice of the pending tool
requests, capped at `PENDING_REQUEST_SUMMARY_CAP = 5` oldest-first:

  pendingRequests: Array<{ id; kind; tool; since }>

`pendingRequestsCount` remains the authoritative total;
`pendingRequestKinds` is still derived from the FULL request set so a
single `'input'` request beyond the cap still surfaces its kind on the
session row.

The tooltip primitive (`HoverTooltip`) is a CSS-driven reveal — no
portal, no positioning JS — so it composes cheaply inside the existing
session-row `<button>` and stays out of the way on touch devices, which
keep getting the same `aria-label` the old `title=""` attribute provided
to screen readers.

Test coverage: shared derivation + cap + tie-break + full-set kind
behaviour; web tooltip render across all four attention kinds plus
mixed-kind overflow suppression and aria-label exposure.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: heavygee

shared/src/sessionSummary.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from 'bun:test'
 import type { Session } from './schemas'
-import { getPendingRequestKinds, toSessionSummary } from './sessionSummary'
+import {
+    PENDING_REQUEST_SUMMARY_CAP,
+    getPendingRequestKinds,
+    getPendingRequests,
+    toSessionSummary
+} from './sessionSummary'
 
 function makeSession(overrides: Partial<Session> = {}): Session {
     return {
@@ -87,4 +92,101 @@ describe('toSessionSummary', () => {
 
         expect(summary.metadata?.lifecycleState).toBe('archived')
     })
+
+    it('includes structured pendingRequests for hover-tooltip copy', () => {
+        const summary = toSessionSummary(makeSession({
+            updatedAt: 5000,
+            agentState: {
+                requests: {
+                    req1: { tool: 'Bash', arguments: {}, createdAt: 100 },
+                    req2: { tool: 'AskUserQuestion', arguments: {}, createdAt: 50 },
+                    req3: { tool: 'Edit', arguments: {} }
+                }
+            }
+        }))
+
+        expect(summary.pendingRequestsCount).toBe(3)
+        expect(summary.pendingRequestKinds).toEqual(['permission', 'input'])
+        expect(summary.pendingRequests).toHaveLength(3)
+        expect(summary.pendingRequests[0]).toEqual({
+            id: 'req2',
+            kind: 'input',
+            tool: 'AskUserQuestion',
+            since: 50
+        })
+        expect(summary.pendingRequests[1]).toEqual({
+            id: 'req1',
+            kind: 'permission',
+            tool: 'Bash',
+            since: 100
+        })
+        expect(summary.pendingRequests[2]).toEqual({
+            id: 'req3',
+            kind: 'permission',
+            tool: 'Edit',
+            since: 5000
+        })
+    })
+
+    it('returns empty pendingRequests when agentState has no requests', () => {
+        const summary = toSessionSummary(makeSession({ agentState: null }))
+        expect(summary.pendingRequests).toEqual([])
+    })
+})
+
+describe('getPendingRequests', () => {
+    it('caps the array length while leaving pendingRequestsCount untouched', () => {
+        const requests: Record<string, { tool: string; arguments: unknown; createdAt: number }> = {}
+        for (let i = 0; i < PENDING_REQUEST_SUMMARY_CAP + 3; i += 1) {
+            requests[`req-${i.toString().padStart(2, '0')}`] = {
+                tool: 'Bash',
+                arguments: {},
+                createdAt: i
+            }
+        }
+        const session = makeSession({ agentState: { requests } })
+
+        const slice = getPendingRequests(session)
+        expect(slice).toHaveLength(PENDING_REQUEST_SUMMARY_CAP)
+        // Oldest-first → the first `cap` items by createdAt should win.
+        expect(slice.map(r => r.id)).toEqual(
+            Array.from({ length: PENDING_REQUEST_SUMMARY_CAP }, (_, i) => `req-${i.toString().padStart(2, '0')}`)
+        )
+
+        const summary = toSessionSummary(session)
+        expect(summary.pendingRequestsCount).toBe(PENDING_REQUEST_SUMMARY_CAP + 3)
+        expect(summary.pendingRequests).toHaveLength(PENDING_REQUEST_SUMMARY_CAP)
+    })
+
+    it('breaks ties on createdAt by id (stable across hub restarts)', () => {
+        const session = makeSession({
+            agentState: {
+                requests: {
+                    'req-b': { tool: 'Bash', arguments: {}, createdAt: 100 },
+                    'req-a': { tool: 'Edit', arguments: {}, createdAt: 100 }
+                }
+            }
+        })
+        const slice = getPendingRequests(session)
+        expect(slice.map(r => r.id)).toEqual(['req-a', 'req-b'])
+    })
+})
+
+describe('getPendingRequestKinds', () => {
+    it('reads from the FULL request set (not the capped pendingRequests slice)', () => {
+        const requests: Record<string, { tool: string; arguments: unknown; createdAt: number }> = {}
+        // First CAP requests are all permission, last one is input — must still
+        // surface 'input' even though it would fall outside the capped slice.
+        for (let i = 0; i < PENDING_REQUEST_SUMMARY_CAP; i += 1) {
+            requests[`perm-${i}`] = { tool: 'Bash', arguments: {}, createdAt: i }
+        }
+        requests['ask'] = {
+            tool: 'AskUserQuestion',
+            arguments: {},
+            createdAt: PENDING_REQUEST_SUMMARY_CAP + 100
+        }
+
+        const kinds = getPendingRequestKinds(makeSession({ agentState: { requests } }))
+        expect(kinds).toEqual(['permission', 'input'])
+    })
 })

shared/src/sessionSummary.ts

@@ -10,6 +10,25 @@ const INPUT_REQUEST_TOOLS = new Set([
     'request_user_input'
 ])
 
+/** Cap on `pendingRequests` carried in `SessionSummary`. The list is meant for
+ *  per-row hover copy ("Approve `Bash`, `Edit` (+1 more)"); deep inspection
+ *  should use `Session.agentState.requests`. The `pendingRequestsCount` field
+ *  is the authoritative total — `pendingRequests.length` may be smaller. */
+export const PENDING_REQUEST_SUMMARY_CAP = 5
+
+export type PendingRequest = {
+    id: string
+    kind: PendingRequestKind
+    tool: string
+    /** Epoch ms when the request was raised; falls back to `session.updatedAt`
+     *  for older requests that were stored without `createdAt`. */
+    since: number
+}
+
+function classifyKind(tool: string): PendingRequestKind {
+    return INPUT_REQUEST_TOOLS.has(tool) ? 'input' : 'permission'
+}
+
 export type SessionSummaryMetadata = {
     name?: string
     path: string
@@ -31,12 +50,43 @@ export type SessionSummary = {
     todoProgress: { completed: number; total: number } | null
     pendingRequestsCount: number
     pendingRequestKinds: PendingRequestKind[]
+    /** Capped, oldest-first slice of pending tool requests. Use this for tooltip
+     *  / per-row UX. The full count (which may exceed the cap) is in
+     *  `pendingRequestsCount`. */
+    pendingRequests: PendingRequest[]
     backgroundTaskCount: number
     futureScheduledMessageCount: number
     model: string | null
     effort: string | null
 }
 
+export function getPendingRequests(
+    session: Session,
+    cap: number = PENDING_REQUEST_SUMMARY_CAP
+): PendingRequest[] {
+    const requests = session.agentState?.requests
+    if (!requests) {
+        return []
+    }
+
+    const items: PendingRequest[] = []
+    for (const [id, request] of Object.entries(requests)) {
+        items.push({
+            id,
+            kind: classifyKind(request.tool),
+            tool: request.tool,
+            since: typeof request.createdAt === 'number' ? request.createdAt : session.updatedAt
+        })
+    }
+
+    items.sort((a, b) => {
+        if (a.since !== b.since) return a.since - b.since
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0
+    })
+
+    return cap >= items.length ? items : items.slice(0, cap)
+}
+
 export function getPendingRequestKinds(session: Session): PendingRequestKind[] {
     const requests = session.agentState?.requests
     if (!requests) {
@@ -45,7 +95,7 @@ export function getPendingRequestKinds(session: Session): PendingRequestKind[] {
 
     const kinds = new Set<PendingRequestKind>()
     for (const request of Object.values(requests)) {
-        kinds.add(INPUT_REQUEST_TOOLS.has(request.tool) ? 'input' : 'permission')
+        kinds.add(classifyKind(request.tool))
     }
 
     return kinds.has('permission') && kinds.has('input')
@@ -88,6 +138,7 @@ export function toSessionSummary(session: Session): SessionSummary {
         todoProgress,
         pendingRequestsCount,
         pendingRequestKinds: getPendingRequestKinds(session),
+        pendingRequests: getPendingRequests(session),
         backgroundTaskCount: session.backgroundTaskCount ?? 0,
         futureScheduledMessageCount: 0,
         model: session.model,

shared/src/types.ts

@@ -24,7 +24,8 @@ export type {
     WorktreeMetadata
 } from './schemas'
 
-export type { SessionSummary, SessionSummaryMetadata, PendingRequestKind } from './sessionSummary'
+export type { SessionSummary, SessionSummaryMetadata, PendingRequest, PendingRequestKind } from './sessionSummary'
+export { PENDING_REQUEST_SUMMARY_CAP } from './sessionSummary'
 export { AGENT_MESSAGE_PAYLOAD_TYPE } from './modes'
 
 export type {

web/src/components/HoverTooltip.tsx

@@ -0,0 +1,65 @@
+import { useId, type ReactNode } from 'react'
+import { cn } from '@/lib/utils'
+
+/**
+ * Lightweight CSS-driven tooltip used by the session list to surface "why is
+ * this indicator showing?" copy on hover/focus. Pure CSS reveal (no portal,
+ * no positioning JS) keeps the component cheap and avoids z-index surprises
+ * inside the session-row `<button>`.
+ *
+ * Touch devices get the `aria-label` (announced) but no visible bubble — the
+ * row is tap-to-open, so the dot deliberately does not capture touch events.
+ *
+ * Layout: tooltip flips to top-anchored when `side='top'`, otherwise hangs
+ * below. Content is wrapped to `max-w-[14rem]` so long tool names don't blow
+ * out the sidebar.
+ */
+export function HoverTooltip(props: {
+    /** Plain-text label used for `aria-label` and screen readers. */
+    label: string
+    /** Visible target element (the dot, the icon, etc.). */
+    target: ReactNode
+    /** Rich tooltip content. Plain text or a small fragment with headings/lists. */
+    children: ReactNode
+    side?: 'top' | 'bottom'
+    align?: 'start' | 'center' | 'end'
+    className?: string
+}) {
+    const id = useId()
+    const side = props.side ?? 'bottom'
+    const align = props.align ?? 'center'
+
+    const alignClasses =
+        align === 'start' ? 'left-0'
+        : align === 'end' ? 'right-0'
+        : 'left-1/2 -translate-x-1/2'
+
+    return (
+        <span className={cn('relative inline-flex group', props.className)}>
+            <span
+                aria-describedby={id}
+                aria-label={props.label}
+                className="inline-flex"
+            >
+                {props.target}
+            </span>
+            <span
+                role="tooltip"
+                id={id}
+                className={cn(
+                    'pointer-events-none absolute z-30 max-w-[14rem] whitespace-normal',
+                    'rounded-md border border-[var(--app-border)] bg-[var(--app-bg)]',
+                    'px-2 py-1 text-xs leading-snug text-[var(--app-fg)] shadow-md',
+                    side === 'top' ? 'bottom-full mb-1' : 'top-full mt-1',
+                    alignClasses,
+                    'opacity-0 invisible',
+                    'group-hover:opacity-100 group-hover:visible',
+                    'group-focus-within:opacity-100 group-focus-within:visible',
+                    'transition-opacity duration-100'
+                )}
+            >
+                {props.children}
+            </span>
+        </span>
+    )
+}