TUI Epic 4: Topology screen

[TraderSamwise]

Fourth epic of the TUI IA redesign. Adds the Topology screen — a structural map of the project (the dashboard is the actionable list lens; topology is the tree + health lens).

What changed

Phase 1 — Topology model. New pure src/project-topology.ts: buildProjectTopology({projectName, worktrees}) → {projectName, health, counts, worktrees[], rows[]}. A TopologyHealth (active/attention/idle/offline) is derived per node via healthForStatus (mirroring the app's openrig-topology semantics) and rolled up per worktree and project. Returns a flattened rows list (worktree ▸ agents/services, with jump ids). Unit-tested.

Phase 2 — Topology screen (key t). A health-dotted tree (project ▸ worktree ▸ agents/services) with a summary header, detail pane, and Enter to jump to an agent/service. Wired like the other subscreens (union, statusline tab, nav cycle, dispatch, render switch, footer + help). t was freed by the Coordination merge (was threads).

Verification

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

Dashboard and Graveyard untouched.

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added a new Topology dashboard screen (shortcut: t), showing an aggregated view of project worktrees, agents, and services with health indicators.
  • Implemented topology interactions: row navigation (j/k or arrows), direct selection (1–9), sidebar toggle (tab), refresh (r), help (?), exit (q), and activation (enter/return).

• UI/UX Updates

  • Updated dashboard help text and overlays to reflect topology shortcuts and key hints.
  • Added topology rendering/details to the dashboard TUI and status line.

• Tests

  • Added unit tests for project topology health and rollup calculations.

[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 6:37am

[TraderSamwise]

@coderabbitai review

[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.

[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: e7a82591-d179-4af9-9f5d-4f398d13e47a

📥 Commits

Reviewing files that changed from the base of the PR and between 9da4807 and a970464.

📒 Files selected for processing (1)

• src/tui/screens/subscreen-renderers.ts

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

• src/tui/screens/subscreen-renderers.ts

---

📝 Walkthrough

Walkthrough

Adds a new "topology" dashboard screen. A pure project-topology module computes health rollup from project/worktree/session/service inputs. The multiplexer gains topology and topologyIndex state, a full key-input handler, and three exported entry points wired into all existing dispatch paths. The TUI receives a list renderer, a details sidebar, and updated help text.

Changes

Topology Dashboard Screen

Layer / File(s)	Summary
Project topology data model and tests src/project-topology.ts, src/project-topology.test.ts	Defines TopologyHealth, TopologyRow, TopologyWorktreeView, ProjectTopology, and ProjectTopologyInput types; implements healthForStatus, rollupHealth, and buildProjectTopology; tests cover status mapping, rollup priority, aggregate counts, special worktree states (pending/removing), and empty project.
Dashboard screen type and state registration src/dashboard/state.ts, src/dashboard/ui-state-store.ts, src/statusline-model.ts	Adds "topology" to DashboardScreen union, VALID_SCREENS persistence set, StatuslineData.dashboardScreen union, and DASHBOARD_SCREEN_TABS.
Multiplexer topology controller and state src/multiplexer/index.ts, src/multiplexer/topology.ts	Adds topology and topologyIndex private fields to Multiplexer; implements refreshTopology, showTopology, renderTopology, findTopologySession, and handleTopologyKey with full key-driven navigation (sidebar toggle, exit, refresh, row nav, row activation).
Multiplexer dispatch wiring src/multiplexer/dashboard-actions-methods.ts, src/multiplexer/dashboard-control.ts, src/multiplexer/dashboard-interaction.ts, src/multiplexer/navigation.ts, src/multiplexer/runtime-state.ts, src/multiplexer/session-launch.ts	Wires topology methods into dashboardActionMethods; adds "t" key handling to subscreen navigation, main dashboard key handler, and help key handler; routes "topology" in renderCurrentDashboardView; forwards stdin to handleTopologyKey in runDashboard.
TUI topology renderers and help text src/tui/screens/subscreen-renderers.ts, src/tui/screens/dashboard-renderers.ts, src/tui/screens/overlay-renderers.ts	Adds renderTopologyScreen (health-dot, summary header, selectable row list with split-screen sidebar) and renderTopologyDetails (details sidebar); updates all buildHelpLine() branches to include [t] topology; adds t → topology entry to the help overlay.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant stdin as stdin handler
  participant topology as topology.ts
  participant model as project-topology.ts
  participant renderer as subscreen-renderers.ts

  rect rgba(100, 149, 237, 0.5)
    Note over User,renderer: Opening the topology screen
    User->>stdin: press "t"
    stdin->>topology: showTopology(host)
    topology->>model: buildProjectTopology(input)
    model-->>topology: ProjectTopology
    topology->>renderer: renderTopologyScreen(ctx)
    renderer-->>User: topology list + details sidebar
  end

  rect rgba(144, 238, 144, 0.5)
    Note over User,renderer: Navigating and activating a row
    User->>stdin: press "j" / "k"
    stdin->>topology: handleTopologyKey(host, data)
    topology->>topology: update topologyIndex
    topology->>renderer: renderTopology → renderTopologyScreen
    renderer-->>User: updated selection
    User->>stdin: press "enter"
    topology->>topology: findTopologySession / activateService
    topology-->>User: session or service activated
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• TraderSamwise/aimux#135: Both PRs touch the dashboard help-line/text rendering in the TUI (src/tui/screens/dashboard-renderers.ts): the prior PR refactors dashboard rendering via the new theme helpers, while this PR adds the new [t] topology shortcut to those generated help hints.
• TraderSamwise/aimux#149: Both PRs touch the TUI help/footer key-hint rendering (e.g., tui/screens/dashboard-renderers.ts and tui/screens/overlay-renderers.ts), so the topology shortcut display in this PR overlaps with the prior PR's refactor of those same help-line components.

Poem

🐇 Hop through the topology tree,
Each worktree a node I can see!
Press t to unveil,
The health without fail —
active, idle, or offline we'll be! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.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 describes the main change: introducing the Topology screen as the fourth epic in the TUI redesign, which aligns with the comprehensive PR scope.
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-15

---

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

[TraderSamwise]

Sub-agent review pass. Two findings, both fixed:

• Stale graveyard footer (med): it still advertised the pre-redesign cluster [d/a/n/y/t/p/g] — n is a dead key and t/p now map to different screens. Normalized every subscreen footer to the current full set [d/a/i/y/p/t/g]. (a970464)
• Dead ternary (low): focusLine = rows.length === 0 ? 1 : 1 simplified to = 1. (a970464)

Model (health rollup, pending/removing precedence, rows order, counts, empty), controller (index clamp, render purity, Enter-jump guards), and the rest of the wiring reviewed clean.