fix(ui): resolve TUI streaming rendering and background agent lifecycle issues

package.json

@@ -33,6 +33,7 @@
         "dev": "bun run src/cli.ts",
         "build": "bun build src/cli.ts --compile --outfile atomic",
         "test": "bun test",
+        "test:contracts": "bun test src/ui/utils/background-agent-provider-parity.test.ts src/ui/utils/background-agent-runtime-parity.test.ts src/ui/utils/background-agent-acceptance.test.ts src/ui/utils/background-agent-termination-integration.test.ts src/ui/utils/background-agent-keybinding-nonconflict.test.ts src/ui/utils/background-agent-parent-callback.test.ts",
         "typecheck": "tsc --noEmit",
         "lint": "oxlint --config=oxlint.json src",
         "lint:fix": "oxlint --config=oxlint.json --fix src",

research/branch-tasks.md

@@ -0,0 +1,26 @@
+# Branch: fix/tui-streaming-rendering
+
+## Overview
+
+This branch addresses TUI bugs related to **streaming content rendering and visual output** across all agents (Claude Code, OpenCode, GitHub Copilot).
+
+## Issues
+
+### #259 — Streaming text blocks clumped together
+Thinking traces are not rendered as separate parts during streaming. Text blocks get clumped together instead of being visually distinct.
+
+### #258 — Background agents UI
+Footer status bar, Ctrl+F termination flow, and tree view hints are not implemented for background agents. Affects Dev & Production.
+
+### #254 — Subagent output is final state instead of returning control
+When a subagent completes, its output is shown as a final state rather than returning control back to the main agent's output stream.
+
+### #248 — Occasional formatting issues from reviewer agent
+Sub-agent output (particularly the reviewer agent) occasionally has formatting/rendering issues in the TUI.
+
+### #231 — Reasoning indicator and timer continue after 100%
+The reasoning indicator and elapsed timer keep running even after task progress has reached 100%.
+
+## Grouping Rationale
+
+All issues in this branch relate to how the TUI **renders and displays streamed content** — text blocks, agent output, progress indicators, and background agent status. Fixing these together ensures a consistent and correct rendering pipeline.

research/docs/2026-02-23-gh-issue-258-background-agents-ui.md

@@ -0,0 +1,86 @@
+---
+date: 2026-02-23 02:06:44 UTC
+researcher: OpenCode
+git_commit: f674c962807d5926f0f19633e66192e7d8ce1039
+branch: fix/tui-streaming-rendering
+repository: fix-tui-streaming-rendering
+topic: "GitHub issue extraction: #258 Background agents UI"
+tags: [research, github, issue-258, tui, background-agents]
+status: complete
+last_updated: 2026-02-23
+last_updated_by: OpenCode
+---
+
+# Research
+
+## Research Question
+Extract all available information and image assets from GitHub issue #258 using `gh`.
+
+## Summary
+Issue `#258` is open and labeled `bug`, authored by `lavaman131`, with no issue comments currently present. The issue body includes five screenshot assets hosted on `raw.githubusercontent.com` and a detailed problem statement covering footer status behavior, Ctrl+F termination, and agent tree hint behavior.
+
+## GitHub Extraction (via gh)
+
+### Issue metadata
+- Issue: `#258`
+- Title: `[BUG] TUI: Background agents UI — footer status bar, Ctrl+F termination flow, and tree view hints not implemented — Claude Code, OpenCode, Copilot — Dev & Production`
+- State: `OPEN`
+- Author: `lavaman131`
+- Labels: `bug`
+- Created: `2026-02-22T20:31:58Z`
+- Updated: `2026-02-22T20:34:37Z`
+- URL: `https://github.com/flora131/atomic/issues/258`
+
+Source command output: `gh issue view 258 --json number,title,state,author,createdAt,updatedAt,url,labels,body`
+
+### Timeline events
+- Labeled `bug` at `2026-02-22T20:31:59Z`
+- Referenced by commit `92b9badb08a9b3d0a3243cd4ec8c140c190d2744` at `2026-02-23T00:07:57Z`
+
+Source command output: `gh api repos/flora131/atomic/issues/258/events`
+
+### Referenced commit from timeline
+- Commit: `92b9badb08a9b3d0a3243cd4ec8c140c190d2744`
+- Message: `docs(research): add branch task breakdown for TUI streaming rendering`
+- Changed file includes `research/branch-tasks.md`
+- Commit URL: `https://github.com/flora131/atomic/commit/92b9badb08a9b3d0a3243cd4ec8c140c190d2744`
+
+Source command output: `gh api repos/flora131/atomic/commits/92b9badb08a9b3d0a3243cd4ec8c140c190d2744`
+
+### Issue comments
+- No issue comments returned.
+
+Source command output: `gh api repos/flora131/atomic/issues/258/comments`
+
+## Extracted Image Assets
+
+All screenshot URLs were extracted from the issue body using `gh issue view 258 --json body -q .body | rg -o 'https://[^)\\s]+'`.
+
+1. Background Agent Tree UI (Running state)
+   - URL: `https://raw.githubusercontent.com/flora131/atomic/lavaman131/hotfix/ralph-workflow/tmux-screenshots/background-task-subagent/background-agent-tree-ui.png`
+   - Caption text in issue: three task agents running, expanded tree view.
+
+2. Background Agent Tree UI (Initializing state)
+   - URL: `https://raw.githubusercontent.com/flora131/atomic/lavaman131/hotfix/ralph-workflow/tmux-screenshots/background-task-subagent/background-agent-tree-ui0.png`
+   - Caption text in issue: two task agents initializing with `0 tool uses`.
+
+3. Background Agent Chatbox UI (footer hint)
+   - URL: `https://raw.githubusercontent.com/flora131/atomic/lavaman131/hotfix/ralph-workflow/tmux-screenshots/background-task-subagent/background-agent-chatbox-ui.png`
+   - Caption text in issue: footer status bar with agent count and `ctrl+f` termination hint.
+
+4. Confirmation Background Agents
+   - URL: `https://raw.githubusercontent.com/flora131/atomic/lavaman131/hotfix/ralph-workflow/tmux-screenshots/background-task-subagent/confirmation-background-agents.png`
+   - Caption text in issue: first Ctrl+F press confirmation prompt.
+
+5. Chat Message Background Sub Agent Terminated
+   - URL: `https://raw.githubusercontent.com/flora131/atomic/lavaman131/hotfix/ralph-workflow/tmux-screenshots/background-task-subagent/chat-message-background-sub-agent-kill.png`
+   - Caption text in issue: chat confirmation `All background agents killed` after second Ctrl+F.
+
+## Historical Context Linkage
+- `research/branch-tasks.md` includes issue grouping text for `#258` and explicitly states `Affects Dev & Production`.
+
+## Related Research
+- `research/tickets/2026-02-23-0258-background-agents-ui.md`
+
+## Open Questions
+- The issue body lists explicit "missing" behaviors; codebase state at this research timestamp is documented separately in the ticket research artifact.