feat(web-ui): /sessions list page + sidebar navigation entry (#508)

## Summary

- New `/sessions` page listing active and ended sessions, sorted active-first
- Session cards: state dot (green/gray), short ID, workspace name, model, relative time, formatted cost, Resume/View/End buttons
- New Session modal with workspace path input, model selector, loading state, form reset on reopen
- `/sessions/[id]` placeholder page (detail view depends on #501 backend)
- Sessions nav entry in AppSidebar with active-session count badge (gray theme, 30s poll)
- New types: `Session`, `SessionState`, `SessionListResponse`, `SessionCreateRequest`
- `sessionsApi` client: `getAll` (wraps `Session[]` array from backend), `create`, `end`

## Validation

- Review feedback: All addressed (2 rounds — internal code review + CodeRabbit/Claude CI reviews)
- Demo: All 9 acceptance criteria verified
- Tests: 112/112 passing (TDD)
- CI: All checks green
- Linting: Clean

Closes #508

Author: frankbria

README.md

@@ -268,7 +268,7 @@ CodeFRAME v2 (Phases 1–6 complete) delivers the full Think-Build-Prove-Ship lo
 - **SHIP**: GitHub PR workflow, environment validation, task self-diagnosis
 - **Engine adapters**: Claude Code, Codex, OpenCode, Kilocode, and built-in ReAct — all via `--engine` flag
 - **Server layer** (optional): FastAPI with 16+ v2 routers, API key auth, rate limiting, SSE streaming, WebSocket endpoints (agent chat, interactive terminal), OpenAPI docs
-- **Web UI**: Workspace view, PRD discovery, Task board, Blocker resolution, Review/commit, PROOF9 requirements and evidence views, TUI dashboard, agent chat panel with streaming tool-call display, interactive terminal for session workspaces
+- **Web UI**: Workspace view, PRD discovery, Task board, Blocker resolution, Review/commit, PROOF9 requirements and evidence views, TUI dashboard, agent chat panel with streaming tool-call display, interactive terminal for session workspaces, Sessions list with active-session badge
 - **Test suite**: 4200+ tests, 88% coverage
 
 ---

web-ui/__tests__/components/layout/AppSidebar.test.tsx

@@ -25,10 +25,15 @@ jest.mock('@/lib/workspace-storage', () => ({
   getSelectedWorkspacePath: jest.fn(),
 }));
 
-// Mock SWR (used for blocker badge count)
+// Mock SWR (used for blocker + session badge counts)
+const mockSWRData: Record<string, unknown> = {};
 jest.mock('swr', () => ({
   __esModule: true,
-  default: () => ({ data: undefined, isLoading: false, error: undefined }),
+  default: (key: string | null) => ({
+    data: key ? mockSWRData[key] : undefined,
+    isLoading: false,
+    error: undefined,
+  }),
 }));
 
 import { getSelectedWorkspacePath } from '@/lib/workspace-storage';
@@ -48,6 +53,8 @@ describe('AppSidebar', () => {
   beforeEach(() => {
     jest.clearAllMocks();
     mockUsePathname.mockReturnValue('/');
+    // Clear SWR mock data to prevent cross-test cache leakage
+    Object.keys(mockSWRData).forEach((k) => delete mockSWRData[k]);
   });
 
   it('renders nothing when no workspace is selected', () => {
@@ -63,16 +70,18 @@ describe('AppSidebar', () => {
     expect(screen.getByText('PRD')).toBeInTheDocument();
   });
 
-  it('renders all 6 navigation items', () => {
+  it('renders all 8 navigation items', () => {
     mockGetWorkspacePath.mockReturnValue('/home/user/projects/test');
     render(<AppSidebar />);
 
     expect(screen.getByText('Workspace')).toBeInTheDocument();
     expect(screen.getByText('PRD')).toBeInTheDocument();
     expect(screen.getByText('Tasks')).toBeInTheDocument();
     expect(screen.getByText('Execution')).toBeInTheDocument();
+    expect(screen.getByText('Sessions')).toBeInTheDocument();
     expect(screen.getByText('Blockers')).toBeInTheDocument();
     expect(screen.getByText('Review')).toBeInTheDocument();
+    expect(screen.getByText('Proof')).toBeInTheDocument();
   });
 
   it('renders enabled items as links', () => {
@@ -112,4 +121,38 @@ describe('AppSidebar', () => {
     // Active items have 'bg-accent' without 'hover:' prefix; inactive have 'hover:bg-accent/50'
     expect(workspaceLink.className).not.toMatch(/(?<!\w)bg-accent(?!\/)/);
   });
+
+  // ─── Sessions nav entry tests ──────────────────────────────────────
+
+  it('renders Sessions nav link pointing to /sessions', () => {
+    mockGetWorkspacePath.mockReturnValue('/home/user/projects/test');
+    render(<AppSidebar />);
+    const sessionsLink = screen.getByRole('link', { name: /sessions/i });
+    expect(sessionsLink).toHaveAttribute('href', '/sessions');
+  });
+
+  it('shows active session count badge when there are active sessions', () => {
+    mockGetWorkspacePath.mockReturnValue('/home/user/projects/test');
+    mockSWRData['/api/v2/sessions?path=%2Fhome%2Fuser%2Fprojects%2Ftest&state=active'] = {
+      sessions: [
+        { id: 's1', state: 'active' },
+        { id: 's2', state: 'active' },
+      ],
+      total: 2,
+    };
+    render(<AppSidebar />);
+    expect(screen.getByText('2')).toBeInTheDocument();
+  });
+
+  it('does not show session badge when count is 0', () => {
+    mockGetWorkspacePath.mockReturnValue('/home/user/projects/test');
+    mockSWRData['/api/v2/sessions?path=%2Fhome%2Fuser%2Fprojects%2Ftest&state=active'] = {
+      sessions: [],
+      total: 0,
+    };
+    render(<AppSidebar />);
+    // With 0 sessions and no blockers, no badge spans should be present
+    const sessionsLink = screen.getByRole('link', { name: /sessions/i });
+    expect(sessionsLink.querySelector('.bg-muted')).toBeNull();
+  });
 });

web-ui/__tests__/components/sessions/NewSessionModal.test.tsx

@@ -0,0 +1,75 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { NewSessionModal } from '@/components/sessions/NewSessionModal';
+
+const defaultProps = {
+  open: true,
+  onOpenChange: jest.fn(),
+  defaultWorkspacePath: '/home/user/projects/my-app',
+  onSubmit: jest.fn().mockResolvedValue(undefined),
+};
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('NewSessionModal', () => {
+  it('renders when open is true', () => {
+    render(<NewSessionModal {...defaultProps} />);
+    expect(screen.getByText('New Session')).toBeInTheDocument();
+  });
+
+  it('does not render when open is false', () => {
+    render(<NewSessionModal {...defaultProps} open={false} />);
+    expect(screen.queryByText('New Session')).not.toBeInTheDocument();
+  });
+
+  it('pre-fills workspace path from prop', () => {
+    render(<NewSessionModal {...defaultProps} />);
+    const input = screen.getByLabelText(/workspace/i);
+    expect(input).toHaveValue('/home/user/projects/my-app');
+  });
+
+  it('defaults model to claude-sonnet-4-6', () => {
+    render(<NewSessionModal {...defaultProps} />);
+    // The select trigger should show the default value
+    expect(screen.getByText('claude-sonnet-4-6')).toBeInTheDocument();
+  });
+
+  it('calls onSubmit with workspace_path and model on submit', async () => {
+    const user = userEvent.setup();
+    render(<NewSessionModal {...defaultProps} />);
+    await user.click(screen.getByRole('button', { name: /start session/i }));
+    await waitFor(() => {
+      expect(defaultProps.onSubmit).toHaveBeenCalledWith({
+        workspace_path: '/home/user/projects/my-app',
+        model: 'claude-sonnet-4-6',
+      });
+    });
+  });
+
+  it('disables Start Session button while submitting', async () => {
+    const onSubmit = jest.fn().mockReturnValue(new Promise(() => {})); // never resolves
+    const user = userEvent.setup();
+    render(<NewSessionModal {...defaultProps} onSubmit={onSubmit} />);
+    await user.click(screen.getByRole('button', { name: /start session/i }));
+    await waitFor(() => {
+      expect(screen.getByRole('button', { name: /start session/i })).toBeDisabled();
+    });
+  });
+
+  it('allows editing the workspace path', async () => {
+    const user = userEvent.setup();
+    render(<NewSessionModal {...defaultProps} />);
+    const input = screen.getByLabelText(/workspace/i);
+    await user.clear(input);
+    await user.type(input, '/other/path');
+    await user.click(screen.getByRole('button', { name: /start session/i }));
+    await waitFor(() => {
+      expect(defaultProps.onSubmit).toHaveBeenCalledWith({
+        workspace_path: '/other/path',
+        model: 'claude-sonnet-4-6',
+      });
+    });
+  });
+});

web-ui/__tests__/components/sessions/SessionCard.test.tsx

@@ -0,0 +1,139 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { SessionCard } from '@/components/sessions/SessionCard';
+import type { Session } from '@/types';
+
+// ─── Fixtures ───────────────────────────────────────────────────────
+
+function makeSession(overrides: Partial<Session> = {}): Session {
+  return {
+    id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeee1234',
+    state: 'active',
+    workspace_path: '/home/user/projects/my-app',
+    model: 'claude-sonnet-4-6',
+    created_at: new Date(Date.now() - 5 * 60 * 1000).toISOString(), // 5 min ago
+    ended_at: null,
+    cost_usd: 0.012,
+    agent_name: null,
+    ...overrides,
+  };
+}
+
+const defaultHandlers = {
+  onEnd: jest.fn(),
+};
+
+function renderCard(sessionOverrides: Partial<Session> = {}, props: Partial<Parameters<typeof SessionCard>[0]> = {}) {
+  const session = makeSession(sessionOverrides);
+  return render(
+    <SessionCard
+      session={session}
+      {...defaultHandlers}
+      {...props}
+    />
+  );
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+// ─── Tests ──────────────────────────────────────────────────────────
+
+describe('SessionCard', () => {
+  it('renders the session short ID (last 8 chars)', () => {
+    renderCard();
+    expect(screen.getByText('eeee1234')).toBeInTheDocument();
+  });
+
+  it('renders the workspace basename', () => {
+    renderCard();
+    expect(screen.getByText('my-app')).toBeInTheDocument();
+  });
+
+  it('renders the model name', () => {
+    renderCard();
+    expect(screen.getByText('claude-sonnet-4-6')).toBeInTheDocument();
+  });
+
+  it('renders cost formatted as dollar amount', () => {
+    renderCard({ cost_usd: 0.012 });
+    expect(screen.getByText('$0.0120')).toBeInTheDocument();
+  });
+
+  it('shows green state dot for active sessions', () => {
+    renderCard({ state: 'active' });
+    const dot = screen.getByTestId('session-state-dot');
+    expect(dot).toHaveClass('bg-green-500');
+  });
+
+  it('shows gray state dot for ended sessions', () => {
+    renderCard({ state: 'ended' });
+    const dot = screen.getByTestId('session-state-dot');
+    expect(dot).toHaveClass('bg-gray-400');
+  });
+
+  it('shows gray state dot for paused sessions', () => {
+    renderCard({ state: 'paused' });
+    const dot = screen.getByTestId('session-state-dot');
+    expect(dot).toHaveClass('bg-gray-400');
+  });
+
+  it('shows Resume button for active sessions', () => {
+    renderCard({ state: 'active' });
+    expect(screen.getByRole('link', { name: /resume/i })).toBeInTheDocument();
+    expect(screen.queryByRole('link', { name: /^view$/i })).not.toBeInTheDocument();
+  });
+
+  it('shows View button for ended sessions', () => {
+    renderCard({ state: 'ended' });
+    expect(screen.getByRole('link', { name: /view/i })).toBeInTheDocument();
+    expect(screen.queryByRole('link', { name: /resume/i })).not.toBeInTheDocument();
+  });
+
+  it('shows End button for active sessions', () => {
+    renderCard({ state: 'active' });
+    expect(screen.getByRole('button', { name: /end/i })).toBeInTheDocument();
+  });
+
+  it('hides End button for ended sessions', () => {
+    renderCard({ state: 'ended' });
+    expect(screen.queryByRole('button', { name: /end/i })).not.toBeInTheDocument();
+  });
+
+  it('calls onEnd when End button is clicked and confirmed', async () => {
+    const user = userEvent.setup();
+    window.confirm = jest.fn().mockReturnValue(true);
+    renderCard({ state: 'active' });
+    await user.click(screen.getByRole('button', { name: /end/i }));
+    expect(window.confirm).toHaveBeenCalled();
+    expect(defaultHandlers.onEnd).toHaveBeenCalledWith('aaaaaaaa-bbbb-cccc-dddd-eeeeeeee1234');
+  });
+
+  it('does not call onEnd when confirm is cancelled', async () => {
+    const user = userEvent.setup();
+    window.confirm = jest.fn().mockReturnValue(false);
+    renderCard({ state: 'active' });
+    await user.click(screen.getByRole('button', { name: /end/i }));
+    expect(window.confirm).toHaveBeenCalled();
+    expect(defaultHandlers.onEnd).not.toHaveBeenCalled();
+  });
+
+  it('renders relative time for created_at', () => {
+    renderCard();
+    // date-fns formatDistanceToNow will produce something like "5 minutes ago"
+    expect(screen.getByText(/minutes? ago/i)).toBeInTheDocument();
+  });
+
+  it('links Resume button to /sessions/[id]', () => {
+    renderCard({ state: 'active' });
+    const link = screen.getByRole('link', { name: /resume/i });
+    expect(link).toHaveAttribute('href', '/sessions/aaaaaaaa-bbbb-cccc-dddd-eeeeeeee1234');
+  });
+
+  it('links View button to /sessions/[id]', () => {
+    renderCard({ state: 'ended' });
+    const link = screen.getByRole('link', { name: /view/i });
+    expect(link).toHaveAttribute('href', '/sessions/aaaaaaaa-bbbb-cccc-dddd-eeeeeeee1234');
+  });
+});