TUI Epic 1: merge Inbox/Threads/Workflow into a Coordination screen

[TraderSamwise]

First epic of the TUI information-architecture redesign (see north-star plan): the dashboard subscreens had drifted from how aimux is actually used. This collapses the three coordination-related tabs into one.

What changed

Phase 1 — Unify the notification data source. The TUI inbox read exchange.inbox via a bespoke loadNotificationEntries (hardcoding unread/cleared), diverging from the app/CLI which use listNotifications over notification-tagged threads. Both TUI surfaces (full screen + panel overlay) now source from listNotifications and mutate via markNotificationsRead/clearNotifications, so read/clear state is real and consistent everywhere.

Phase 2 — Merge Inbox + Threads + Workflow → one Coordination screen. A single notifications-led screen with two sections:

• Inbox — the real notification feed.
• Threads — task-aware, all thread kinds (via buildWorkflowEntries({allKinds})), with task/handoff/review lifecycle actions.

Tab switches sections. Accept moved to A so it no longer collides with the a activity-nav key (the old lowercase accept was dead, shadowed by nav). Direct cutover: removed workflow/threads/notifications from the DashboardScreen union and rewired all routing (nav cycle, key dispatch, render switch, hotkey action, footer + help, statusline tabs). Net ~-600 lines.

Verification

• yarn typecheck, yarn lint, yarn build clean
• yarn vitest run — 1376 tests pass

Dashboard layout and Graveyard are untouched, as scoped.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a unified “coordination” dashboard view that merges notifications and threads with keyboard-driven section switching.

• Bug Fixes & Improvements

  • Updated keyboard shortcuts and help text to reflect the new coordination view.
  • Improved restoring dashboard UI state by migrating legacy screen selections and providing a safe fallback when unknown.

• Refactor

  • Removed the legacy workflow, threads, and notifications screens in favor of coordination.

• Tests

  • Expanded/adjusted coverage for screen migration and coordination key handling.

[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 4:16am

[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: fbc6330a-d8ce-4702-aea3-b5d84803e4e8

📥 Commits

Reviewing files that changed from the base of the PR and between a75660e and 5afe323.

📒 Files selected for processing (3)

• src/dashboard/ui-state-store.test.ts
• src/dashboard/ui-state-store.ts
• src/multiplexer/subscreens.ts

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

• src/multiplexer/subscreens.ts

---

📝 Walkthrough

Walkthrough

Three separate dashboard subscreens — workflow, threads, and notifications — are consolidated into a single "coordination" screen. A new coordination.ts multiplexer handles unified key routing between notification and thread sections. The notifications module is updated to use a new listNotifications/markNotificationsRead/clearNotifications API. All type contracts, key bindings, routing surfaces, TUI renderers, and persisted state normalization are updated accordingly.

Changes

Coordination Screen Consolidation

Layer / File(s)	Summary
Type contracts and Multiplexer state shape src/dashboard/state.ts, src/hotkeys.ts, src/statusline-model.ts, src/multiplexer/index.ts, src/workflow.ts	DashboardScreen, HotkeyAction, StatuslineData, and DASHBOARD_SCREEN_TABS replace workflow/threads/notifications with "coordination". Multiplexer state gains notificationEntries, notificationIndex, and coordinationSection. buildWorkflowEntries gains an allKinds opt; buildCoordinationThreadEntries is added.
New coordination.ts multiplexer src/multiplexer/coordination.ts	New 224-line module implementing showCoordination, renderCoordination, and handleCoordinationKey. Handles keyboard navigation for both notification and thread sections, including lifecycle actions (task accept/complete, thread status, review approve/reject), read/clear for notifications, and section toggling.
Notifications API refactor src/multiplexer/notifications.ts	Replaces runtime exchange inbox logic with listNotifications/markNotificationsRead/clearNotifications. Removes showNotifications/renderNotifications exports; exports openSelectedNotification and refreshNotificationEntries; redirects post-open rendering to host.renderCoordination().
Subscreens refactor and thread lifecycle wiring src/multiplexer/subscreens.ts	Removes twelve legacy exports (workflow/thread/notification screen functions). Introduces refreshCoordinationThreads helper. Updates openRelevantThreadForSession, handleThreadReplyKey, and all four thread lifecycle action paths to use buildCoordinationThreadEntries and host.renderCoordination().
Dashboard routing, key bindings, and action wiring src/multiplexer/session-launch.ts, src/multiplexer/runtime-state.ts, src/multiplexer/dashboard-actions-methods.ts, src/multiplexer/dashboard-control.ts, src/multiplexer/dashboard-interaction.ts, src/multiplexer/navigation.ts, src/hotkeys.ts, src/metadata-server.ts	All key-binding surfaces ("i", "y", "t") and action dispatch (handleAction, runDashboard, handleHelpKey) are updated to route through coordination. dashboardActionMethods adds coordination wrappers and removes fifteen legacy method wrappers. /control/open-inbox now sets screen to "coordination".
TUI coordination screen renderers and help text src/tui/screens/subscreen-renderers.ts, src/tui/screens/dashboard-renderers.ts, src/tui/screens/overlay-renderers.ts	Adds renderCoordinationScreen and renderCoordinationDetails (with notification and thread detail sub-renderers), replacing eight removed screen/detail renderer exports. Updates help footer and overlay key-binding labels to [i] coordination; removes [y] workflow entry.
Dashboard state persistence and normalization src/dashboard/ui-state-store.ts	Implements normalizePersistedScreen helper with VALID_SCREENS to validate and remap legacy screen values ("notifications", "threads", "workflow") to "coordination", with fallback to "dashboard" for unrecognized values.
Test updates for coordination routing src/multiplexer/notifications.test.ts, src/multiplexer/subscreens.test.ts, src/dashboard/ui-state-store.test.ts	Notifications tests switch from handleNotificationsKey to handleCoordinationKey, add renderCoordination mock, and simplify notification record creation. Subscreens tests set coordinationSection and use renderCoordinationDetails. UI state store test updates "workflow" references and adds migration/fallback test cases.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant HotkeyHandler
  participant handleAction
  participant runDashboard
  participant showCoordination
  participant renderCoordinationScreen

  rect rgba(70, 130, 180, 0.5)
    Note over User,renderCoordinationScreen: Activating coordination screen
    User->>HotkeyHandler: press "i"
    HotkeyHandler->>handleAction: dispatch { type: "coordination" }
    handleAction->>runDashboard: set dashboardScreen = "coordination"
    runDashboard->>showCoordination: initialize UI state, refresh entries
    showCoordination->>renderCoordinationScreen: render two-pane coordination layout
    renderCoordinationScreen-->>User: Inbox / Threads split-screen shown
  end

  rect rgba(60, 179, 113, 0.5)
    Note over User,renderCoordinationScreen: Key navigation within coordination
    User->>runDashboard: keypress (e.g. Tab, Enter, "r", "d")
    runDashboard->>handleCoordinationKey: route to coordination handler
    handleCoordinationKey->>handleNotificationsSectionKey: (if coordinationSection="notifications")
    handleNotificationsSectionKey->>openSelectedNotification: Enter/Return
    openSelectedNotification->>markNotificationsRead: mark entry read
    openSelectedNotification->>renderCoordinationScreen: re-render after open
    handleCoordinationKey->>handleThreadsSectionKey: (if coordinationSection="threads")
    handleThreadsSectionKey->>runTaskLifecycleAction: lifecycle key pressed
    handleThreadsSectionKey->>refreshCoordinationThreads: rebuild + re-render
    refreshCoordinationThreads->>renderCoordinationScreen: updated thread list
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• TraderSamwise/aimux#33: Overlapping changes in src/multiplexer/notifications.ts and inbox/coordination notification wiring, specifically around the transition from runtime exchange store to a dedicated notifications API.
• TraderSamwise/aimux#135: Both PRs modify src/tui/screens/dashboard-renderers.ts help-line construction; the retrieved PR refactors the underlying helper, this PR changes the coordination-related key labels it emits.

Poem

🐇 Three screens once roamed where rabbits feared to tread,
Workflow, threads, and inbox — now coordination instead!
One [i] key to rule them, one tab to switch between,
The tidiest of dashboards this warren's ever seen.
I hopped through the diff and clapped my paws with glee — ✨
Less code, more coordination, just the way it should be!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 4.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 PR title clearly and concisely summarizes the primary change: consolidating three coordination-related screens (Inbox, Threads, Workflow) into a single Coordination screen. It is specific, descriptive, and accurately represents the main objective of the changeset.
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-12

---

_{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 (CodeRabbit returned an incremental no-op with no findings). Findings + resolutions:

Fixed

• Stale persisted screen (high): a dashboardScreen persisted before this merge (notifications/threads/workflow) was restored verbatim into the narrowed union. Now normalized → coordination, with unknown values falling back to dashboard (ui-state-store.ts, + 2 tests). (5afe323)
• NaN thread index (med): refreshCoordinationThreads now guards a non-numeric threadIndex before clamping. (5afe323)

Intentional / not regressions (no change)

• length > 1 arrow-nav guard and on-demand (r) thread refresh both match the prior three screens' behavior exactly — single-item lists are already selected, and the old Threads screen never auto-refreshed either.
• t no longer opens a screen: deliberate — Threads is merged into Coordination (i), Tab switches sections. Footer/help updated accordingly.
• Duplicate up/down/jump logic across the two section handlers: minor; left readable rather than over-abstracted.