headquarter/openspec/changes/session-list-overhaul/design.md

Context

The current session list implementation duplicates rendering logic across dashboard.tsx and sessions.tsx. Both pages fetch the same data, apply similar filtering (active vs recent/stopped), and render session cards with inconsistent styling and controls. The dashboard has a compact grid view while the sessions page has a list view, but neither provides all control actions (open, stop, start, delete) in a consistent way.

Goals / Non-Goals

Goals:

• Unified session card component with all control actions visible and accessible
• Unified session list component that handles filtering, grouping, and empty states
• Consistent visual design across dashboard and sessions pages
• Clear status indicators (running, stopped, error, building, etc.)
• Project/repository context visible on each card
• Responsive layout that works on mobile and desktop

Non-Goals:

• No API changes
• No new session management features (just better UI for existing ones)
• No changes to session creation flow
• No real-time updates beyond existing polling

Decisions

Decision: Two levels of components

• SessionCard: Individual session display with actions
• SessionList: Container that handles grouping and layout This allows the dashboard to use SessionList directly while the sessions page can add additional filtering/controls around it.

Decision: Card-based layout over table Cards provide better mobile experience and can show richer information (project context, tool icon, status badge). Tables are harder to make responsive.

Decision: Inline actions on cards Each card shows primary action (Open for running, Start for stopped) and secondary actions in a dropdown or secondary button row. This matches the existing dashboard pattern but makes it consistent.

Decision: Status colors

• Running: green
• Building/Starting/Probing: yellow/amber
• Stopped: gray
• Error: red
• Unhealthy: orange

Risks / Trade-offs

Risk: Breaking existing dashboard layout → Mitigation: Keep the same grid layout structure, just swap the inner rendering to use SessionCard

Risk: Mobile experience with many action buttons → Mitigation: Use icon buttons on mobile, text buttons on desktop. Collapse secondary actions into a "..." menu.

Migration Plan

1. Create SessionCard and SessionList components
2. Update dashboard.tsx to use SessionList
3. Update sessions.tsx to use SessionList
4. Remove old duplicated session rendering code
5. Update styles
6. Test both pages

Open Questions

None