feat: session list UX — recent-12h section, cross-device pin, unread badge

Three additive features on the session list:

1. Recent (last 12h) section
   A flat list at the top of the session list, showing every session
   updated in the last 12 hours regardless of project, sorted active-
   first then by recency. Same SessionItem rendering as folder rows
   with showPath=true so users can tell which project each entry
   belongs to. Hidden during search.

2. Pin sessions (cross-device, server-side)
   Long-press a session and pick "置顶 / Pin to top" to keep it at
   the top of Recent permanently, even past the 12h window. Pin state
   lives on the server in session metadata (metadata.pinnedAt: epoch
   ms) so it syncs across browser tabs / devices via SSE. Cleared by
   tapping the same menu item again.

   - Hub: sessionCache.pinSession + syncEngine wrapper
   - Hub: POST /api/sessions/:id/pin { pinned: boolean }
   - Shared: PinSessionRequestSchema, pinnedAt on MetadataSchema +
     SessionSummaryMetadata (copied through toSessionSummary)
   - Web: usePinnedSessions hook derives from session metadata, uses
     useMutation to call the API; sort + display in SessionList

3. Unread badge — synced with push notification triggers
   When NotificationHub fires a ready / permission / task / session-
   completion push, it also fire-and-forgets a markSessionUnread on
   the syncEngine, which writes metadata.unreadAt = Date.now() with
   a version-mismatch retry. Sessions with unreadAt show a small
   #007AFF dot before the title in the list. When SessionChat mounts
   (or while it's open and a new unreadAt arrives) it calls
   POST /api/sessions/:id/mark-read which clears the flag and SSE
   broadcasts the cleared state to every device.

Build: 44 → 48.

via [HAPI](https://hapi.run)

Co-Authored-By: HAPI <noreply@hapi.run>

Author: yoyoworms

hub/src/notifications/notificationHub.test.ts

@@ -9,6 +9,8 @@ const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
 class FakeSyncEngine {
     private readonly listeners: Set<SyncEventListener> = new Set()
     private readonly sessions: Map<string, Session> = new Map()
+    readonly unreadMarks: string[] = []
+    readonly readMarks: string[] = []
 
     subscribe(listener: SyncEventListener): () => void {
         this.listeners.add(listener)
@@ -23,6 +25,14 @@ class FakeSyncEngine {
         this.sessions.set(session.id, session)
     }
 
+    async markSessionUnread(sessionId: string): Promise<void> {
+        this.unreadMarks.push(sessionId)
+    }
+
+    async markSessionRead(sessionId: string): Promise<void> {
+        this.readMarks.push(sessionId)
+    }
+
     emit(event: SyncEvent): void {
         for (const listener of this.listeners) {
             listener(event)
@@ -122,6 +132,45 @@ describe('NotificationHub', () => {
         hub.stop()
     })
 
+    it('marks session unread when a ready notification fires', async () => {
+        const engine = new FakeSyncEngine()
+        const channel = new StubChannel()
+        const hub = new NotificationHub(engine as unknown as SyncEngine, [channel], {
+            permissionDebounceMs: 1,
+            readyCooldownMs: 1
+        })
+
+        const session = createSession()
+        engine.setSession(session)
+
+        const readyEvent: SyncEvent = {
+            type: 'message-received',
+            sessionId: session.id,
+            message: {
+                id: 'message-1',
+                seq: 1,
+                localId: null,
+                createdAt: 0,
+                content: {
+                    role: 'agent',
+                    content: {
+                        id: 'event-1',
+                        type: 'event',
+                        data: { type: 'ready' }
+                    }
+                }
+            }
+        }
+
+        engine.emit(readyEvent)
+        await sleep(5)
+
+        expect(channel.readySessions).toHaveLength(1)
+        expect(engine.unreadMarks).toEqual([session.id])
+
+        hub.stop()
+    })
+
     it('throttles ready notifications per session', async () => {
         const engine = new FakeSyncEngine()
         const channel = new StubChannel()

hub/src/notifications/notificationHub.ts

@@ -220,7 +220,16 @@ export class NotificationHub {
         await this.notifySessionCompletion(session, reason)
     }
 
+    // Mark the session as unread on the same triggers that fire a push.
+    // Fire-and-forget so a metadata write failure doesn't disrupt the push path.
+    private markSessionUnreadAsync(sessionId: string): void {
+        this.syncEngine.markSessionUnread(sessionId).catch((error) => {
+            console.error('[NotificationHub] Failed to mark session unread:', error)
+        })
+    }
+
     private async notifyReady(session: Session): Promise<void> {
+        this.markSessionUnreadAsync(session.id)
         for (const channel of this.channels) {
             try {
                 await channel.sendReady(session)
@@ -231,6 +240,7 @@ export class NotificationHub {
     }
 
     private async notifyPermission(session: Session): Promise<void> {
+        this.markSessionUnreadAsync(session.id)
         for (const channel of this.channels) {
             try {
                 await channel.sendPermissionRequest(session)
@@ -241,6 +251,7 @@ export class NotificationHub {
     }
 
     private async notifyTask(session: Session, notification: TaskNotification): Promise<void> {
+        this.markSessionUnreadAsync(session.id)
         for (const channel of this.channels) {
             try {
                 await channel.sendTaskNotification(session, notification)
@@ -251,6 +262,7 @@ export class NotificationHub {
     }
 
     private async notifySessionCompletion(session: Session, reason: SessionEndReason): Promise<void> {
+        this.markSessionUnreadAsync(session.id)
         for (const channel of this.channels) {
             if (typeof channel.sendSessionCompletion !== 'function') {
                 continue

hub/src/sync/sessionCache.ts

@@ -506,6 +506,104 @@ export class SessionCache {
         this.refreshSession(sessionId)
     }
 
+    async pinSession(sessionId: string, pinned: boolean): Promise<void> {
+        const session = this.sessions.get(sessionId)
+        if (!session) {
+            throw new Error('Session not found')
+        }
+
+        const currentMetadata = session.metadata ?? { path: '', host: '' }
+        const { pinnedAt: _existing, ...rest } = currentMetadata as { pinnedAt?: number | null } & Record<string, unknown>
+        const newMetadata = pinned
+            ? { ...rest, pinnedAt: Date.now() }
+            : rest
+
+        const result = this.store.sessions.updateSessionMetadata(
+            sessionId,
+            newMetadata as typeof currentMetadata,
+            session.metadataVersion,
+            session.namespace,
+            { touchUpdatedAt: false }
+        )
+
+        if (result.result === 'error') {
+            throw new Error('Failed to update session metadata')
+        }
+
+        if (result.result === 'version-mismatch') {
+            throw new Error('Session was modified concurrently. Please try again.')
+        }
+
+        this.refreshSession(sessionId)
+    }
+
+    // Mark a session as having "unread" activity that the user should look at.
+    // Triggered by the same events that fire a push notification (ready,
+    // permission request, task notification, session completion). Best-effort:
+    // we retry once on a version-mismatch and otherwise swallow errors so the
+    // notification path doesn't fail because of metadata churn.
+    async markSessionUnread(sessionId: string): Promise<void> {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const session = this.sessions.get(sessionId)
+            if (!session) return
+
+            const currentMetadata = session.metadata ?? { path: '', host: '' }
+            if ((currentMetadata as { unreadAt?: number | null }).unreadAt) {
+                return
+            }
+
+            const newMetadata = { ...currentMetadata, unreadAt: Date.now() }
+
+            const result = this.store.sessions.updateSessionMetadata(
+                sessionId,
+                newMetadata,
+                session.metadataVersion,
+                session.namespace,
+                { touchUpdatedAt: false }
+            )
+
+            if (result.result === 'success') {
+                this.refreshSession(sessionId)
+                return
+            }
+            if (result.result === 'error') {
+                return
+            }
+            this.refreshSession(sessionId)
+            // version-mismatch: loop and try again with the refreshed version
+        }
+    }
+
+    async markSessionRead(sessionId: string): Promise<void> {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const session = this.sessions.get(sessionId)
+            if (!session) return
+
+            const currentMetadata = session.metadata ?? { path: '', host: '' }
+            const { unreadAt: existing, ...rest } = currentMetadata as { unreadAt?: number | null } & Record<string, unknown>
+            if (existing == null) {
+                return
+            }
+
+            const result = this.store.sessions.updateSessionMetadata(
+                sessionId,
+                rest as typeof currentMetadata,
+                session.metadataVersion,
+                session.namespace,
+                { touchUpdatedAt: false }
+            )
+
+            if (result.result === 'success') {
+                this.refreshSession(sessionId)
+                return
+            }
+            if (result.result === 'error') {
+                return
+            }
+            this.refreshSession(sessionId)
+        }
+    }
+
     async deleteSession(sessionId: string): Promise<void> {
         const session = this.sessions.get(sessionId)
         if (!session) {

hub/src/sync/syncEngine.ts

@@ -520,6 +520,18 @@ export class SyncEngine {
         await this.sessionCache.renameSession(sessionId, name)
     }
 
+    async pinSession(sessionId: string, pinned: boolean): Promise<void> {
+        await this.sessionCache.pinSession(sessionId, pinned)
+    }
+
+    async markSessionUnread(sessionId: string): Promise<void> {
+        await this.sessionCache.markSessionUnread(sessionId)
+    }
+
+    async markSessionRead(sessionId: string): Promise<void> {
+        await this.sessionCache.markSessionRead(sessionId)
+    }
+
     async deleteSession(sessionId: string): Promise<void> {
         await this.sessionCache.deleteSession(sessionId)
     }

hub/src/web/routes/sessions.ts

@@ -2,6 +2,7 @@ import {
     DeleteUploadRequestSchema,
     getPermissionModesForFlavor,
     isPermissionModeAllowedForFlavor,
+    PinSessionRequestSchema,
     RenameSessionRequestSchema,
     ResumeSessionRequestSchema,
     SessionCollaborationModeRequestSchema,
@@ -316,6 +317,50 @@ export function createSessionsRoutes(getSyncEngine: () => SyncEngine | null): Ho
         return c.json({ ok: true })
     })
 
+    app.post('/sessions/:id/pin', async (c) => {
+        const engine = requireSyncEngine(c, getSyncEngine)
+        if (engine instanceof Response) {
+            return engine
+        }
+
+        const sessionResult = requireSessionFromParam(c, engine)
+        if (sessionResult instanceof Response) {
+            return sessionResult
+        }
+
+        const body = await c.req.json().catch(() => null)
+        const parsed = PinSessionRequestSchema.safeParse(body)
+        if (!parsed.success) {
+            return c.json({ error: 'Invalid body: pinned (boolean) is required' }, 400)
+        }
+
+        try {
+            await engine.pinSession(sessionResult.sessionId, parsed.data.pinned)
+            return c.json({ ok: true })
+        } catch (error) {
+            const message = error instanceof Error ? error.message : 'Failed to update pin state'
+            if (message.includes('concurrently') || message.includes('version')) {
+                return c.json({ error: message }, 409)
+            }
+            return c.json({ error: message }, 500)
+        }
+    })
+
+    app.post('/sessions/:id/mark-read', async (c) => {
+        const engine = requireSyncEngine(c, getSyncEngine)
+        if (engine instanceof Response) {
+            return engine
+        }
+
+        const sessionResult = requireSessionFromParam(c, engine)
+        if (sessionResult instanceof Response) {
+            return sessionResult
+        }
+
+        await engine.markSessionRead(sessionResult.sessionId)
+        return c.json({ ok: true })
+    })
+
     app.post('/sessions/:id/switch', async (c) => {
         const engine = requireSyncEngine(c, getSyncEngine)
         if (engine instanceof Response) {

shared/src/apiTypes.ts

@@ -131,6 +131,12 @@ export const RenameSessionRequestSchema = z.object({
 
 export type RenameSessionRequest = z.infer<typeof RenameSessionRequestSchema>
 
+export const PinSessionRequestSchema = z.object({
+    pinned: z.boolean()
+})
+
+export type PinSessionRequest = z.infer<typeof PinSessionRequestSchema>
+
 export const UploadFileRequestSchema = z.object({
     filename: z.string().min(1).max(255),
     content: z.string().min(1),

shared/src/schemas.ts

@@ -54,7 +54,9 @@ export const MetadataSchema = z.object({
     archiveReason: z.string().optional(),
     flavor: z.string().nullish(),
     capabilities: SessionCapabilitiesSchema.optional(),
-    worktree: WorktreeMetadataSchema.optional()
+    worktree: WorktreeMetadataSchema.optional(),
+    pinnedAt: z.number().nullish(),
+    unreadAt: z.number().nullish()
 })
 
 export type Metadata = z.infer<typeof MetadataSchema>

shared/src/sessionSummary.ts

@@ -9,6 +9,8 @@ export type SessionSummaryMetadata = {
     flavor?: string | null
     worktree?: WorktreeMetadata
     agentSessionId?: string
+    pinnedAt?: number | null
+    unreadAt?: number | null
 }
 
 export type SessionSummary = {
@@ -41,7 +43,9 @@ export function toSessionSummary(session: Session): SessionSummary {
             ?? session.metadata.opencodeSessionId
             ?? session.metadata.cursorSessionId
             ?? session.metadata.kimiSessionId
-            ?? undefined
+            ?? undefined,
+        pinnedAt: session.metadata.pinnedAt ?? null,
+        unreadAt: session.metadata.unreadAt ?? null
     } : null
 
     const todoProgress = session.todos?.length ? {

web/build-number.json

@@ -1 +1 @@
-{ "build": 44 }
+{ "build": 48 }

web/src/api/client.ts

@@ -541,6 +541,20 @@ export class ApiClient {
         })
     }
 
+    async pinSession(sessionId: string, pinned: boolean): Promise<void> {
+        await this.request(`/api/sessions/${encodeURIComponent(sessionId)}/pin`, {
+            method: 'POST',
+            body: JSON.stringify({ pinned })
+        })
+    }
+
+    async markSessionRead(sessionId: string): Promise<void> {
+        await this.request(`/api/sessions/${encodeURIComponent(sessionId)}/mark-read`, {
+            method: 'POST',
+            body: JSON.stringify({})
+        })
+    }
+
     async deleteSession(sessionId: string): Promise<void> {
         await this.request(`/api/sessions/${encodeURIComponent(sessionId)}`, {
             method: 'DELETE'