Harden TUI API connection state

[TraderSamwise]

Summary

• refocus the north-star docs around client/API connection-contract reliability
• mark dashboard desktop-state as a critical TUI API resource
• keep the TUI degraded until critical resources recover, even if unrelated API calls succeed

Verification

• yarn vitest src/multiplexer/tui-api-runtime.test.ts src/multiplexer/dashboard-api-client.test.ts src/multiplexer/dashboard-model-service.test.ts
• yarn vitest src/multiplexer/tui-api-runtime.test.ts src/multiplexer/dashboard-api-client.test.ts src/multiplexer/dashboard-model-service.test.ts src/multiplexer/dashboard-model.test.ts src/multiplexer/dashboard-ops.test.ts src/multiplexer/session-launch.test.ts src/multiplexer/project-event-stream.test.ts src/multiplexer/worktrees.test.ts
• yarn typecheck
• yarn lint
• yarn build
• yarn vitest

Summary by CodeRabbit

• New Features

  • Added improved handling for critical app data so the connection state reflects important failures more accurately during transitions.
  • Tightened guidance for the core-sidecar workflow to better define the current focus and next steps.

• Bug Fixes

  • Prevented unrelated successful checks from masking a failure in an important resource.
  • Ensured recovery only returns to a healthy state after the critical resource has successfully refreshed.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jul 6, 2026 3:22am

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 47 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

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

How do review 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 refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: de908fe7-3b27-414d-b470-6f5a131a5d2f

📥 Commits

Reviewing files that changed from the base of the PR and between c76ea17 and 9e3588c.

📒 Files selected for processing (2)

• src/multiplexer/tui-api-runtime.test.ts
• src/multiplexer/tui-api-runtime.ts

📝 Walkthrough

Walkthrough

TuiApiRuntime gains a criticalResources option that tracks which resources must recover before connection state returns to connected. Success paths route through a new markRequestSuccess helper, and refresh failures use shouldRecoverFromResourceFailure. New tests cover degraded-state behavior. Documentation files are also updated.

Changes

Critical resource recovery logic

Layer / File(s)	Summary
Critical resources option and state tracking src/multiplexer/tui-api-runtime.ts	Adds criticalResources option to TuiApiRuntimeOptions and initializes an internal ReadonlySet in the constructor.
Success path routing through markRequestSuccess src/multiplexer/tui-api-runtime.ts	requestJson, mutateJson, and refresh success paths now call markRequestSuccess instead of directly setting state to connected; explicit error clearing on refresh setup is removed.
Resource-failure recovery decision and helpers src/multiplexer/tui-api-runtime.ts	Adds shouldRecoverFromResourceFailure, markRequestSuccess, and hasCriticalResourceFailure helpers; wires desktop-state as a critical resource in getOrCreateTuiApiRuntime.
Runtime tests for critical resource degradation src/multiplexer/tui-api-runtime.test.ts	New tests verify degraded state persists until a critical resource recovers and that wrapper-level success doesn't mask critical resource failure.

Documentation updates

Layer / File(s)	Summary
North-star doc and AGENTS.md text updates AGENTS.md, docs/core-sidecar-north-star.md	Reformats sentence wrapping in AGENTS.md; adds Current Focus section, updates progress date, and rewrites remaining-work/path-forward guidance in the north-star doc.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant TuiApiRuntime
  participant ResourceState

  Caller->>TuiApiRuntime: refresh(resource)
  TuiApiRuntime->>ResourceState: perform request
  ResourceState-->>TuiApiRuntime: failure
  TuiApiRuntime->>TuiApiRuntime: shouldRecoverFromResourceFailure(resource, error, generation)
  alt resource is critical
    TuiApiRuntime->>TuiApiRuntime: set state degraded
  else non-critical and generation stale
    TuiApiRuntime->>TuiApiRuntime: set state degraded
  end
  ResourceState-->>TuiApiRuntime: later success
  TuiApiRuntime->>TuiApiRuntime: markRequestSuccess(generation)
  TuiApiRuntime->>TuiApiRuntime: hasCriticalResourceFailure()
  alt no critical failure remaining
    TuiApiRuntime->>Caller: state connected
  else critical failure remains
    TuiApiRuntime->>Caller: state stays degraded
  end

Loading

Possibly related PRs

• TraderSamwise/aimux#218: Extends the same TuiApiRuntime foundation this PR builds on with criticalResources-aware transitions.
• TraderSamwise/aimux#240: Also modifies tui-api-runtime.ts degradation/recovery gating logic with related test changes.
• TraderSamwise/aimux#269: Introduces recoverOnFailure/shouldRecoverFromRequestFailure, directly overlapping with this PR's recovery decision logic.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: making TUI API connection state more resilient.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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/core-sidecar-next-51

---

_{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.

[coderabbitai]

Actionable comments posted: 1

🤖 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/tui-api-runtime.ts`:
- Around line 243-255: Update the recovery flow in tui-api-runtime so a
successful request can clear the degraded desktop-state; right now
refreshRuntimeGuard() only probes guards and markRequestSuccess() still sees
hasCriticalResourceFailure() as true because desktop-state.error is never reset.
Adjust the recovery path around markRequestSuccess(), refreshRuntimeGuard(), and
the desktop-state resource handling so a successful refresh explicitly
re-fetches or clears desktop-state before setConnectionState("connected") is
allowed.

🪄 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: 4bafb998-5d0e-4f04-9f56-0d898a8ab8e3

📥 Commits

Reviewing files that changed from the base of the PR and between cb79330 and c76ea17.

📒 Files selected for processing (4)

• AGENTS.md
• docs/core-sidecar-north-star.md
• src/multiplexer/tui-api-runtime.test.ts
• src/multiplexer/tui-api-runtime.ts