TUI Epic 2: Project observability screen

[TraderSamwise]

Second epic of the TUI IA redesign. Adds the Project observability screen — a terminal-native overview of what's happening across the project, derived from the project's current direction (not a port of the app GUI).

What changed

Phase 1 — Node observability model. New pure src/project-observability.ts: buildProjectObservability({sessions, services, worktrees, tasks, notifications}) → {summary, progress, story}. No I/O; unit-tested directly.

• summary: agents (running/waiting/offline), services, worktrees, open/done tasks, unread notifications.
• progress: task counts by status (pending/assigned/in-progress/blocked/done/failed + total).
• story: tasks + notifications merged into one newest-first feed.

Phase 2 — Project TUI screen. New read-only screen (key y): summary rollup + task-progress breakdown + a selectable story feed with a detail pane. Wired like the other subscreens (DashboardScreen union, statusline tab, nav cycle, key dispatch, render switch, footer + help). y was freed by the Coordination merge and has no action-key collision.

This is where Workflow's task data now surfaces as the progress lens (the other half — actionable task items — lives in Coordination from Epic 1).

Verification

• yarn typecheck, yarn lint, yarn build clean
• yarn vitest run — 1383 tests pass (5 new model tests)

Dashboard and Graveyard untouched.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a new “project” dashboard screen with centralized visibility (status summary, task progress, and a recent activity feed).
  • Accessible via the [y] shortcut from the main dashboard and help overlay; includes a details sidebar for the selected item.
  • Updated help/shortcut displays to surface the new [y] project navigation.
• Tests
  • Added coverage for project observability aggregation and story generation/sorting.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 17, 2026 5:30am

[TraderSamwise]

@coderabbitai review

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a457e40b-eb51-48f4-abf6-47deb4bcf1dd

📥 Commits

Reviewing files that changed from the base of the PR and between f0e07cf and 8428fbc.

📒 Files selected for processing (1)

• src/multiplexer/project.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/multiplexer/project.ts

---

📝 Walkthrough

Walkthrough

A new "project" dashboard screen is introduced end-to-end: a buildProjectObservability module aggregates session/task/notification data into summary, progress, and story structures; TUI renderers display the two-pane project view; the multiplexer wires routing, stdin dispatch, and action methods; and the "y" keyboard shortcut is registered across all navigation and help surfaces.

Changes

Project Dashboard Screen

Layer / File(s)	Summary
ProjectObservability data contracts and aggregation src/project-observability.ts, src/project-observability.test.ts	Exports ProjectSummary, TaskProgress, ProjectStoryItem, ProjectObservability, ProjectObservabilityInput, and ProjectStoryKind. Implements buildProjectObservability to compute session/task/notification rollups and a newest-first story list with storyLimit cap. Tests cover summary rollups, progress counts, story merge/sort, review-task tagging, storyLimit enforcement, and empty-input handling.
DashboardScreen type, VALID_SCREENS, and Multiplexer state src/dashboard/state.ts, src/dashboard/ui-state-store.ts, src/multiplexer/index.ts	Adds "project" to the DashboardScreen union and VALID_SCREENS list. Introduces projectObservability and projectIndex as private Multiplexer members.
project.ts: showProject, renderProject, handleProjectKey src/multiplexer/project.ts	Implements refreshProjectObservability to rebuild observability from sessions/tasks/notifications and clamp projectIndex. Implements showProject (clears subscreens, refreshes, switches screen, writes status line, renders) and renderProject (lazy refresh + render). Implements handleProjectKey with sidebar toggle, quit, return-to-dashboard, help, refresh, vertical story navigation, numeric selection 1–9, and delegation fallback.
TUI project screen renderers and status line model src/tui/screens/subscreen-renderers.ts, src/statusline-model.ts	Adds renderProjectScreen and renderProjectDetails with STORY_KIND_DOT tone mapping and two-pane layout composition. Extends StatuslineData.dashboardScreen and DASHBOARD_SCREEN_TABS to include "project".
Multiplexer action methods, routing, and stdin dispatch src/multiplexer/dashboard-actions-methods.ts, src/multiplexer/runtime-state.ts, src/multiplexer/session-launch.ts	Wires showProject/renderProject/handleProjectKey delegating wrappers into dashboardActionMethods. Adds the "project" branch to renderCurrentDashboardView and stdin dispatch in runDashboard.
Keyboard shortcuts and navigation wiring src/multiplexer/dashboard-interaction.ts, src/multiplexer/dashboard-control.ts, src/multiplexer/navigation.ts, src/tui/screens/overlay-renderers.ts, src/tui/screens/dashboard-renderers.ts	Registers the "y" shortcut in the main dashboard key handler, subscreen navigation toggle, help-screen dismissal, help overlay entry, and rendered help line text.

Sequence Diagram(s)

sequenceDiagram
  participant stdin as stdin (keypress "y")
  participant dashboardInteraction as dashboard-interaction
  participant project as project.ts
  participant observability as buildProjectObservability
  participant renderer as renderProjectScreen

  stdin->>dashboardInteraction: onKeyPress("y")
  dashboardInteraction->>project: showProject(host)
  project->>observability: refreshProjectObservability(host)
  observability-->>project: ProjectObservability
  project->>renderer: renderProjectScreen(ctx)
  renderer-->>stdin: frame written to TUI

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• TraderSamwise/aimux#135: Modifies buildHelpLine() in the same dashboard renderer, directly overlapping with this PR's addition of the [y] project shortcut token to help line text.
• TraderSamwise/aimux#157: Touches the same DashboardScreen union, handleDashboardKey, and handleHelpKey code paths around y/i shortcuts and screen routing.

Poem

🐇 A hop and a skip, a new screen appears,
The project view blooms after so many gears!
Press y on your keyboard, the story unfolds,
Tasks, notifications—observability holds.
The rabbit now watches all progress with glee,
From summary to story, the dashboard runs free! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: introducing a new Project observability screen as part of the TUI redesign epic.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/tui-next-13

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[TraderSamwise]

Sub-agent review pass. One finding, fixed:

• Per-keystroke rebuild (med): renderProject called refreshProjectObservability (which reads the exchange store twice via readAllTasks + listNotifications) on every nav keystroke, plus a double-refresh on entry/r. Made renderProject a pure render that only builds the snapshot when missing; refresh now happens on screen entry and the explicit [r] key only. (8428fbc)

Model, controller index-clamping, renderer null/empty handling, and all screen-enumeration wiring reviewed clean.