Skip to content

Harden TUI API runtime settlement#253

Merged
TraderSamwise merged 5 commits into
masterfrom
chore/web-api-parity-next
Jun 27, 2026
Merged

Harden TUI API runtime settlement#253
TraderSamwise merged 5 commits into
masterfrom
chore/web-api-parity-next

Conversation

@TraderSamwise

@TraderSamwise TraderSamwise commented Jun 26, 2026

Copy link
Copy Markdown
Owner

Summary

  • keep TUI navigation behavior consistent after the API-first refactor
  • rehydrate live tmux agent windows into cold project-service API snapshots
  • make aimux restart refresh project services and adopt daemon startup races
  • wait for concrete stop/service-stop state transitions instead of treating a single API refresh as settlement

Verification

  • yarn vitest run src/multiplexer/dashboard-ops.test.ts src/multiplexer/dashboard-model.test.ts src/multiplexer/runtime-state.test.ts src/runtime-restart.test.ts

Summary by CodeRabbit

  • New Features

    • Added lower-case hjkl dashboard navigation, including j/k movement and h/l mode switching.
    • Updated dashboard hints and help text to show the new navigation and action keys.
  • Bug Fixes

    • Improved dashboard behavior for worktree, session, and flat views so selected entries are activated consistently.
    • Refined stop/restart handling so dashboards and services settle more reliably after changes.
    • Improved handling of project-scoped tmux windows and live session recovery.

@vercel

vercel Bot commented Jun 26, 2026

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
app Ready Ready Preview, Comment Jun 27, 2026 12:04am

@coderabbitai

coderabbitai Bot commented Jun 26, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@TraderSamwise, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 29 minutes and 16 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1a5a16c2-989d-4f2d-9e48-98fda408fffe

📥 Commits

Reviewing files that changed from the base of the PR and between dfe70a1 and 2cce3a6.

📒 Files selected for processing (8)
  • src/multiplexer/dashboard-interaction.test.ts
  • src/multiplexer/dashboard-interaction.ts
  • src/multiplexer/dashboard-model.test.ts
  • src/multiplexer/dashboard-model.ts
  • src/multiplexer/dashboard-ops.test.ts
  • src/multiplexer/dashboard-ops.ts
  • src/tui/screens/dashboard-renderers.test.ts
  • src/tui/screens/dashboard-renderers.ts
📝 Walkthrough

Walkthrough

Dashboard keyboard handling now separates plain hjkl navigation from shifted commands, and the footer/help text reflects the new key labels. Project-root-aware tmux lookup now feeds snapshots, runtime reports, stop flows, and restart sequencing.

Changes

Dashboard navigation and hints

Layer / File(s) Summary
Plain hjkl dispatch
src/multiplexer/dashboard-interaction.ts, src/multiplexer/dashboard-interaction.test.ts
handleDashboardKey now routes plain hjkl navigation through a centralized dispatcher, with worktree/session/flat-dashboard tests and shifted H/L command handling.
Footer and help labels
src/tui/screens/dashboard-renderers.ts, src/tui/screens/dashboard-renderers.test.ts, src/tui/screens/overlay-renderers.ts
Dashboard footer hints and help text now show the new navigation and library key labels, and the renderer tests assert the updated key sets.

Project-root tmux runtime flow

Layer / File(s) Summary
Snapshot hydration
src/multiplexer/runtime-state.ts, src/multiplexer/dashboard-model.ts, src/multiplexer/dashboard-model.test.ts, src/multiplexer/runtime-state.test.ts
projectRootFor(host) is added and buildDesktopStateSnapshot hydrates live agent windows when managed windows are missing; tests cover project-root rehydration.
Project-root lookups
src/multiplexer/runtime-state.ts, src/multiplexer/session-runtime-core.ts, src/multiplexer/dashboard-model.ts
tmux managed-window lookup and last-used state now use host.projectRoot across runtime-state, session runtime, and dashboard-model paths.
Dashboard report filtering
src/runtime-coherence.ts, src/runtime-coherence.test.ts
listDashboardReports skips placeholder client windows and reuses pane_start_command for process report args.
Stop settle flow
src/multiplexer/dashboard-ops.ts, src/multiplexer/dashboard-ops.test.ts
Stop mutations now clear stale lifecycle state and wait for running session/service rows to settle offline before completing.
Restart sequencing
src/runtime-restart.ts, src/runtime-restart.test.ts
Control-plane restart now stops each project service before ensuring it again, and the test checks the call order.

Sequence Diagram(s)

sequenceDiagram
  participant restartAimuxControlPlaneUnlocked
  participant ensureDaemonRunning
  participant stopProjectService
  participant ensureService
  restartAimuxControlPlaneUnlocked->>ensureDaemonRunning: ensureDaemonRunning()
  loop each projectRoot
    restartAimuxControlPlaneUnlocked->>stopProjectService: stopProjectService(projectRoot)
    restartAimuxControlPlaneUnlocked->>ensureService: ensureService(projectRoot)
  end
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

Poem

I hop through h j k l by moonlit pane,
with footer hints that sing the tune again.
My burrow knows the right root tree,
and tmux windows snap in harmony.
Hop-hop—one restart, then tea.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 3.33% 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 matches the main theme of the PR, which hardens runtime settlement and related TUI behavior after the API refactor.
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.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch chore/web-api-parity-next

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
src/tui/screens/dashboard-renderers.ts (1)

369-377: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Session-level footer hints still understate the new hjkl bindings.

At session level, j/k move selection and h/l map to back/open in src/multiplexer/dashboard-interaction.ts, but the footer still advertises ↑↓, Enter, and Esc separately with only a generic hjkl nav hint. That makes the new bindings less discoverable than the worktree and flat-list variants. Consider mirroring the combined labels here too (↑↓/jk, Enter/l, Esc/h).

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/tui/screens/dashboard-renderers.ts` around lines 369 - 377, The
session-level footer hints in dashboard rendering still underrepresent the new
hjkl bindings, so update the hint list built in dashboard-renderers.ts to mirror
the combined labels used elsewhere. In the footer returned for the session view,
make the selection, open, and back hints explicitly show the paired shortcuts
from dashboard-interaction.ts (j/k with ↑↓, l with Enter, h with Esc) instead of
only a generic hjkl nav entry, so the displayed hints match the actual
navigation bindings.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/multiplexer/dashboard-interaction.ts`:
- Around line 503-526: Rebuild and commit the generated dist artifacts for this
dashboard runtime change; the behavior update in dashboard-interaction should
not be left only in src. After updating the relevant logic in
dashboard-interaction and any related runtime entrypoints, run yarn build so the
checked-in dist output reflects the new key handling. Verify the build output is
included alongside the src change, since vitest/typecheck coverage alone is not
sufficient for runtime or CLI behavior changes.
- Around line 182-197: The navigation logic in dashboard-interaction.ts is using
Math.max(0, order.indexOf(...)) for the focused worktree, which makes stale
focus skip the first item when moving with j/down and jump to the last item with
k/up. Update the handling in the down/up key cases to detect when
focusedWorktreePath is not found in host.dashboardState.worktreeNavOrder and
reset it to a valid starting position before applying the wraparound step, so
navigation begins from the first worktree instead of an offset index.

In `@src/multiplexer/dashboard-model.ts`:
- Around line 694-695: Thread projectRoot through the remaining project-scoped
reads in computeDashboardSessions and the surrounding dashboard model flow.
Update the loadMetadataState call to use the explicit root instead of implicit
cwd, and pass projectRoot into the findMainRepo path used by worktree resolution
so all metadata and main-checkout lookups stay aligned with the same project.
Keep the existing projectRootFor(host) value as the single source of truth and
propagate it consistently through these reads.
- Around line 59-67: The unhydrated check in hasUnhydratedLiveAgentWindow only
looks for missing session IDs in host.sessions, so it can incorrectly treat
agent windows as hydrated even when sessionWorktreePaths and sessionTmuxTargets
are still empty. Broaden the condition to also detect sessions that exist in
host.sessions but are missing tmux-backed hydration state, and make
buildDesktopStateSnapshot()/restoreTmuxSessionsFromTopology() rely on that
stronger signal so computeDashboardSessions() includes fields like worktreePath
when managedWindows already has them.

In `@src/multiplexer/dashboard-ops.ts`:
- Around line 192-194: The tmux lookup in `hasManagedWindows` is using the
untrimmed `host.projectRoot` even after validating it, so update the
`projectRoot` assignment to preserve the trimmed value before calling
`host.tmuxRuntimeManager.listProjectManagedWindows`. Keep the fix localized
around `host.projectRoot`, `projectRoot`, and the `listProjectManagedWindows`
call so managed-window matching uses the normalized path.

---

Outside diff comments:
In `@src/tui/screens/dashboard-renderers.ts`:
- Around line 369-377: The session-level footer hints in dashboard rendering
still underrepresent the new hjkl bindings, so update the hint list built in
dashboard-renderers.ts to mirror the combined labels used elsewhere. In the
footer returned for the session view, make the selection, open, and back hints
explicitly show the paired shortcuts from dashboard-interaction.ts (j/k with ↑↓,
l with Enter, h with Esc) instead of only a generic hjkl nav entry, so the
displayed hints match the actual navigation bindings.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d56ce170-ea20-4bd4-8067-92e2cad055a1

📥 Commits

Reviewing files that changed from the base of the PR and between 71b1c03 and dfe70a1.

📒 Files selected for processing (16)
  • src/multiplexer/dashboard-interaction.test.ts
  • src/multiplexer/dashboard-interaction.ts
  • src/multiplexer/dashboard-model.test.ts
  • src/multiplexer/dashboard-model.ts
  • src/multiplexer/dashboard-ops.test.ts
  • src/multiplexer/dashboard-ops.ts
  • src/multiplexer/runtime-state.test.ts
  • src/multiplexer/runtime-state.ts
  • src/multiplexer/session-runtime-core.ts
  • src/runtime-coherence.test.ts
  • src/runtime-coherence.ts
  • src/runtime-restart.test.ts
  • src/runtime-restart.ts
  • src/tui/screens/dashboard-renderers.test.ts
  • src/tui/screens/dashboard-renderers.ts
  • src/tui/screens/overlay-renderers.ts

Comment thread src/multiplexer/dashboard-interaction.ts
Comment thread src/multiplexer/dashboard-interaction.ts
Comment thread src/multiplexer/dashboard-model.ts
Comment thread src/multiplexer/dashboard-model.ts
Comment thread src/multiplexer/dashboard-ops.ts Outdated
@TraderSamwise

Copy link
Copy Markdown
Owner Author

Independent review findings resolved in db31fab:

  • src/multiplexer/dashboard-model.ts now resolves the main repo from the host project root instead of process cwd, with regression coverage for cwd/project-root mismatch.
  • src/multiplexer/dashboard-ops.ts now treats any non-running service row as settled for stop operations, including offline rows with stale display-only command/preview fields.

@TraderSamwise

Copy link
Copy Markdown
Owner Author

CodeRabbit outside-diff footer hint item handled in 2cce3a6: session-level dashboard hints now advertise ↑↓/jk, Enter/l, and Esc/h explicitly, with renderer test expectations updated.

@TraderSamwise
TraderSamwise merged commit 0b9ed6d into master Jun 27, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant