Fix TUI runtime instability paths

[TraderSamwise]

Summary

• keep tmux dashboard navigation local unless the dashboard pane is genuinely stale or failed
• suppress visible statusline errors during cache misses and show a static TUI error frame on render crashes
• harden runtime guard and API open flows against stale service identity, escape passthrough, and stale activation focus races
• reject incomplete service snapshots when tmux still has live agent windows

Verification

• yarn vitest --run src/tmux/control-script.test.ts src/tmux/statusline-script.test.ts src/multiplexer/dashboard-view-methods.test.ts src/multiplexer/runtime-guard.test.ts src/multiplexer/dashboard-control.test.ts src/multiplexer/dashboard-model.test.ts
• yarn typecheck
• yarn lint
• yarn build
• yarn vitest --run
• pre-push hook: yarn typecheck && yarn lint && yarn test

Summary by CodeRabbit

• New Features

  • Dashboard errors now render in a clearer static terminal view instead of a blank/cleared screen.
  • Dashboard opening is more reliable, with safer two-step activation and smarter reload behavior.

• Bug Fixes

  • Fixed cases where stale or incomplete dashboard state could trigger incorrect refreshes.
  • Improved runtime guard handling so mismatched service state is reported more accurately.
  • Status line failures are now quieter and less disruptive, while still logging when available.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 24, 2026 8:33am

[coderabbitai]

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 191eec78-5c1a-4b16-9448-776d71852800

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR introduces conditional dashboard reload gating in tmux-control.sh via new staleness predicates, splits dashboard notification-target opening into two focus phases in TypeScript, broadens contradictory-desktop-state detection to per-session ID comparison, improves render-error display with a static ANSI frame, removes Escape key passthrough from the runtime guard, and converts tmux-statusline.sh error exits to silent/logging behavior.

Changes

Dashboard Resilience Improvements

Layer / File(s)	Summary
Conditional dashboard reload in tmux-control.sh scripts/tmux-control.sh, src/tmux/control-script.test.ts	Adds find_dashboard_candidate and dashboard_candidate_needs_reload helpers; focus_local_dashboard_target and fallback_local_control now gate reloads on staleness predicate rather than any switch_local_dashboard failure. Tests cover missing-build-metadata reload and non-metadata-miss no-reload cases.
Silent error-handling in tmux-statusline.sh scripts/tmux-statusline.sh, src/tmux/statusline-script.test.ts	log_error becomes a no-op when log_file is unset; all fail_visible call sites (missing args, missing render files, unsupported-line default) converted to non-terminating log_error/fail_silent. New tests verify no "status err" output and correct log file entries.
Two-phase focus in openProjectServiceNotificationTarget src/multiplexer/dashboard-control.ts, src/multiplexer/dashboard-control.test.ts	Splits the single focus: true notification-target call into a focus: false preflight plus elapsed-time-adjusted focus: true second call. Staleness check between phases prevents stale-token focus requests. Tests use ordered toHaveBeenNthCalledWith and add an invalidation-during-resolve case.
Per-session contradictory-state detection src/multiplexer/dashboard-model.ts, src/multiplexer/dashboard-model.test.ts	Replaces isContradictoryEmptyDesktopState with listLiveTmuxAgentIds/isContradictoryDesktopState that compare live tmux agent sessionIds against service-payload sessions+teammates entries. Test verifies incomplete-state rejection and cache preservation.
Static error frame on dashboard render failure src/multiplexer/dashboard-view-methods.ts, src/multiplexer/dashboard-view-methods.test.ts	Adds buildStaticDashboardRenderErrorFrame producing a clipped ANSI terminal frame; renderDashboard catch handler writes it with viewport-size fallback instead of a bare escape sequence. Test verifies both failure label and thrown error text appear in writeFrame output.
Runtime guard: Escape swallow and health-probe mismatch src/multiplexer/runtime-guard.ts, src/multiplexer/runtime-guard.test.ts	Removes "escape" from GUARD_PASSTHROUGH_KEYS; 2xx health-probe path now emits { kind: "stale", reason: "service-mismatch" } for pid/projectStateDir/serviceInfo mismatches. Tests cover Escape swallow, footer flash, and both mismatch probe variants.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• TraderSamwise/aimux#240: Both PRs modify src/multiplexer/runtime-guard.ts to change how service identity mismatches map to { kind: "stale", reason: "service-mismatch" } states, directly overlapping on the same guard evaluation code path.
• TraderSamwise/aimux#235: Both PRs modify GUARD_PASSTHROUGH_KEYS in src/multiplexer/runtime-guard.ts and associated runtime-guard tests, making the key-passthrough changes directly code-level related.
• TraderSamwise/aimux#225: Both PRs modify openProjectServiceNotificationTarget in src/multiplexer/dashboard-control.ts to re-check dashboard activation lifecycle before issuing focus-related open-target requests.

Poem

🐇 Hoppity-hop through the dashboard gate,
Two phases to focus — never too late!
Escape is now swallowed, no sneaking past,
Stale states are caught before they're cast.
The statusline's silent when things go wrong,
And render errors frame a clear-eyed song! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.76% 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 is broad, but it accurately reflects the PR’s main goal of hardening unstable TUI/runtime paths.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/tui-runtime-resilience-next

---

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

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

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

Caution

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

⚠️ Outside diff range comments (1)

scripts/tmux-control.sh (1)

255-267: 🎯 Functional Correctness | 🟡 Minor

Escape sessionPrefix before building the awk regex
scripts/tmux-control.sh:262
runtime.tmux.sessionPrefix is an arbitrary config string, but this lookup treats it as a regex. A custom prefix with metacharacters (., +, (, |, etc.) can overmatch and resolve the wrong dashboard session. Use an exact field comparison or escape the prefix first.

🤖 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 `@scripts/tmux-control.sh` around lines 255 - 267, The dashboard session lookup
in tmux-control.sh is treating session_prefix as a regex inside the awk filter,
which can overmatch when the configured prefix contains metacharacters. Update
the dashboard_target search logic to either compare the session name field
exactly or escape session_prefix before embedding it in the regex, and keep the
fix localized around the session_prefix assignment and the awk-based lookup.

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

Outside diff comments:
In `@scripts/tmux-control.sh`:
- Around line 255-267: The dashboard session lookup in tmux-control.sh is
treating session_prefix as a regex inside the awk filter, which can overmatch
when the configured prefix contains metacharacters. Update the dashboard_target
search logic to either compare the session name field exactly or escape
session_prefix before embedding it in the regex, and keep the fix localized
around the session_prefix assignment and the awk-based lookup.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2db68491-023f-438e-b4e8-2bdf13309a8e

📥 Commits

Reviewing files that changed from the base of the PR and between c7f7c7e and e97f9ab.

📒 Files selected for processing (12)

• scripts/tmux-control.sh
• scripts/tmux-statusline.sh
• src/multiplexer/dashboard-control.test.ts
• src/multiplexer/dashboard-control.ts
• src/multiplexer/dashboard-model.test.ts
• src/multiplexer/dashboard-model.ts
• src/multiplexer/dashboard-view-methods.test.ts
• src/multiplexer/dashboard-view-methods.ts
• src/multiplexer/runtime-guard.test.ts
• src/multiplexer/runtime-guard.ts
• src/tmux/control-script.test.ts
• src/tmux/statusline-script.test.ts