Files
pipelines/app/notes/session-list-background-tasks.md
alan 45c933c176 Chat list: spinner and background-task badge from server activity on every row
The list applies chat_activity pushes and each row's activity by seq, so
every listed chat shows a running turn, not only the chat open here. An
idle chat with running background tasks wears a quiet badge with tooltip and
semantics "Background tasks running (N)". Older servers keep the old
behaviour. List rows that never changed carry the server's current seq so
they order after snapshots kept from an earlier server process.
2026-11-03 19:53:52 +00:00

3.3 KiB

Session list: turn and background-task indicators

Request: besides the turn spinner, show a quieter indicator on a chat list row when the turn is idle but the session still runs background work (shells, Claude Code background Bash and Agent/Task subagents, Codex command executions, OpenCode shells). Also make the spinner reliable for every listed chat, not only chats this connection opened.

Implemented, with an approved server change.

Server

  • protocol.ChatSession.Activity (activity: turn_running, background_tasks, seq) is set on every chat_sessions row from the hub's own state (internal/server/chat_activity.go, handleChatSessions).
  • chat_activity is pushed to every connection (through chatSessionChanges) when a session's turn starts or ends or its running-shell count changes. It is computed under the hub mutex at those points only: turn admitted or finished, step frames, shell frames, shell readback, and room release. Text and tool chunks never push. seq starts from the wall clock in microseconds, so it orders across a restart.
  • Keep-alive: keepUnattendedLocked keeps an unwatched room while it holds running shells, so their exits are seen and the badge clears. When the last shell exits, the room is released at once (emitRoom) or by the reaper. Bounds: the existing 16-room unattended cap, the 6-hour chatUnattendedTurnLimit (measured from when the room became unattended), and the harness itself. A Claude Code process exit now reports its running background tasks as exited (processExit, internal/claude). A released room reports 0 tasks rather than a stale count.

App

  • ChatSessionsController applies chat_activity and row activity by seq (the larger wins), deriving running and background_tasks on the row. The list re-reads on reconnect (the existing syncToken). A server without activity leaves the list as before.
  • session_activity_badge.dart: the turn spinner, or, when idle with tasks, a muted Icons.pending / CupertinoIcons.ellipsis_circle_fill glyph with tooltip and semantics "Background tasks running (N)". The tooltip shows on hover only (TooltipTriggerMode.manual), so a touch long press stays the row's own gesture.
  • Fixture: ?chats=N&activity=1 in the capture app lists one running chat, one with two background tasks and idle chats (tool/perf/perf_fixture.dart).

Evidence

  • Go: chat_activity_test.go covers the list payload, the pushes on turn start and end and on task start and exit, unattended keep and release on exit, and expiry of a task that never reports an exit. background_tasks_test.go covers the Claude process exit.
  • Flutter: test/features/chat/ui/sessions/chat_sessions_activity_test.dart.
  • Captures (fixture app): Material phone 560x1000, Material desktop 1280x900 with the hover tooltip, and Cupertino dark phone.

Unverified

  • Real harness behaviour. Shell start and exit events come from each adapter's existing translation. Whether a real Codex or OpenCode background command always reports its exit was not exercised against live harnesses here.
  • Background Bash outliving a crashed Claude Code CLI. It is reported exited on process exit, on the assumption that the CLI's tasks end with it.
  • Device (Android/iOS) rendering; only the browser was captured.