Coalesce TUI API recovery probes

[TraderSamwise]

Summary

• replace per-failure immediate guard probes with a debounced/cooldown-aware TUI API recovery scheduler
• route dashboard model refresh success/failure guard probes through the scheduler
• preserve pending recovery when a scheduler probe or direct runtime guard probe is already in flight
• clear scheduler timer/pending/in-flight state on teardown

Verification

• yarn vitest run src/multiplexer/tui-api-runtime.test.ts src/multiplexer/dashboard-model-service.test.ts src/multiplexer/runtime-lifecycle-methods.test.ts
• yarn typecheck && yarn lint
• yarn vitest run && yarn build
• independent sub-agent audit: found external-probe collision; fixed and re-audit clean

Summary by CodeRabbit

• Tests

  • Enhanced test coverage for recovery handling mechanisms and timing scenarios
  • Added validation for state transitions during cleanup operations

• Refactor

  • Improved internal recovery scheduling with refined timing controls and state management for better reliability

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 23, 2026 6:50am

[coderabbitai]

📝 Walkthrough

Walkthrough

scheduleTuiApiRecovery is overhauled from a fixed-delay one-shot timer into a stateful scheduler with debounce and cooldown constants, in-flight/pending tracking, and deferred execution when an external guard probe is active. Dashboard-model call sites are migrated to the new API, teardown resets three new state fields, and tests cover all new timing and concurrency behaviors.

Changes

TUI API Recovery Scheduler

Layer / File(s)	Summary
Recovery scheduler contract and implementation src/multiplexer/tui-api-runtime.ts	Introduces TuiApiRecoveryOptions interface and exports TUI_API_RECOVERY_DEBOUNCE_MS / TUI_API_RECOVERY_COOLDOWN_MS. Replaces the old 25 ms one-shot timer with a computed-delay runner that tracks tuiApiRecoveryInFlight, tuiApiRecoveryPending, and tuiApiRecoveryDueAt, supports awaitable host.refreshRuntimeGuard, and defers when host.runtimeGuardProbing is active.
Dashboard model call site migration src/multiplexer/dashboard-model.ts	Adds scheduleTuiApiRecovery to the import from tui-api-runtime.js and replaces two direct host.refreshRuntimeGuard() calls — in failDashboardServiceRefresh and the applied === true branch of refreshDashboardModelFromService — with scheduleTuiApiRecovery(host, { immediate: true }).
Teardown reset for new recovery state src/multiplexer/runtime-lifecycle-methods.ts, src/multiplexer/runtime-lifecycle-methods.test.ts	teardown now resets tuiApiRecoveryDueAt, tuiApiRecoveryPending, and tuiApiRecoveryInFlight before disposing resources. Test initializes these three fields on the host fixture and asserts all are cleared after teardown.
Scheduler and integration tests src/multiplexer/tui-api-runtime.test.ts, src/multiplexer/dashboard-model-service.test.ts	Updates the coalesces-failures test to advance by TUI_API_RECOVERY_DEBOUNCE_MS; adds tests for cooldown enforcement, in-flight retry, and external-probing deferral; updates dashboard-model-service tests to use vi.waitFor for async guard assertions; replaces a hardcoded timer advance with the constant.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• TraderSamwise/aimux#218: Directly touches tui-api-runtime.ts recovery scheduling and runtime state handling that this PR extends with debounce/cooldown logic.
• TraderSamwise/aimux#221: Introduces or updates scheduleTuiApiRecovery as a replacement for direct host.refreshRuntimeGuard() calls in the same dashboard-model code path.
• TraderSamwise/aimux#226: Modifies the same refreshDashboardModelFromService lifecycle and host.refreshRuntimeGuard call site that this PR migrates to the new scheduler.

Poem

🐰 A timer of 25 ms? Too crude, too blunt!
Now debounce and cooldown guard every stunt.
In-flight? Pending? No double-probe woes,
The rabbit schedules smartly — dueAt it goes!
unref?.() called, no process held tight,
Recovery hops gracefully into the night. 🌙

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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 pull request title "Coalesce TUI API recovery probes" directly and clearly summarizes the main change: consolidating multiple TUI API recovery probes into a debounced scheduler to prevent redundant operations.
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/next-20260623-tui-connection-adapter-8

---

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

[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 247-298: The changes to the scheduler functions
tuiApiRecoveryDelay, runScheduledTuiApiRecovery, and scheduleTuiApiRecovery
affect aimux runtime behavior and require rebuilding distribution artifacts. Run
yarn build to regenerate the dist/ folder with the updated scheduler logic.
Source-level validation alone with yarn vitest and yarn typecheck is
insufficient for runtime behavior changes per coding guidelines.

🪄 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: 29d5fa0a-d116-4d6a-819a-7398597d59df

📥 Commits

Reviewing files that changed from the base of the PR and between 0897162 and 51ea0c9.

📒 Files selected for processing (6)

• src/multiplexer/dashboard-model-service.test.ts
• src/multiplexer/dashboard-model.ts
• src/multiplexer/runtime-lifecycle-methods.test.ts
• src/multiplexer/runtime-lifecycle-methods.ts
• src/multiplexer/tui-api-runtime.test.ts
• src/multiplexer/tui-api-runtime.ts