# Ticket 4.7 — Todo / Progress Overlay

**Phase**: 4 — Frontend UI
**Priority**: Medium
**Depends on**: 4.1

## Description

Sticky overlay showing the agent's current todo list and progress. When the agent uses the `todowrite` tool (lowercase in OpenCode, mapped to `TodoWrite` by the translator), the relay displays the tasks with their status (pending, in_progress, completed) as a persistent overlay that doesn't interfere with the chat.

Note: OpenCode also has a `todoread` tool and a `GET /session/:id/todo` endpoint for fetching the current todo list. OpenCode does NOT have the `TaskCreate`/`TaskUpdate`/`TaskList`/`TaskGet` tool family — the corresponding handlers in claude-relay's tools.js are dead code and can be ignored. Todo state comes exclusively through `todowrite` tool calls.

## Acceptance Criteria

### AC1: Displays todo list from agent

```gherkin
Given the agent has created a todo list via TodoWrite
When the todo data arrives via WebSocket
Then a sticky overlay appears at the top or bottom of the chat
And it shows each task with its status icon:
  - ⏳ pending
  - 🔄 in_progress
  - ✅ completed
```

### AC2: Updates in real-time

```gherkin
Given a todo list is displayed
When the agent updates a task status
Then the overlay updates immediately
And completed tasks show a strikethrough or muted style
And the in_progress task is visually prominent
```

### AC3: Collapsible

```gherkin
Given the todo overlay is displayed
When the user clicks the collapse/minimise button
Then it shrinks to a compact progress bar (e.g., "3/7 tasks done")
And clicking again expands to the full list
```

### AC4: Disappears when empty

```gherkin
Given all tasks are completed
When 5 seconds pass with no new tasks
Then the overlay fades out
And chat area reclaims the space
```

## Testable Components

| Component | Test Type | What to Assert |
|-----------|-----------|----------------|
| Todo data parsing | Unit | Parses todowrite tool output into structured task list |
| Todo rendering | E2E | Tasks shown with correct status icons and ordering |
| Real-time update | E2E | Status changes update icons and styling immediately |
| Collapse/expand | E2E | Toggle switches between full list and compact progress bar |
| Auto-hide | E2E | Overlay fades after all tasks complete, reappears on new tasks |

## Reference

- Claude-relay todo UI: `../claude-relay/lib/public/app.js` (todo overlay section)
- Claude-relay tools: `../claude-relay/lib/public/modules/tools.js`
