fix(desktop): bound backend shutdown wait during quit

[ishaanko]

Problem

The quit-time finalizer stopped every backend instance in the pool with no timeout. If any one backend didn't exit cleanly, the wait never ended, and the app never called app.quit(). Since PR #6562 now destroys the window before this wait, the hang became invisible: holding Cmd+Q looked like it did nothing, and the only way out was a force quit.

Fixes #7598

Fix

Bound the wait to 5 seconds, matching the identical pattern already used for this same operation in apps/desktop/src/updates/DesktopUpdates.ts. On timeout, the close keeps running in the background instead of blocking quit, so a slow-but-healthy shutdown still finishes cleanly, and a genuinely hung one no longer blocks the app from exiting.

Extracted the finalizer's logic into an exported stopAllPoolInstances function so it has a real seam to test against.

Testing

• New test in DesktopBackendManager.test.ts calls the real stopAllPoolInstances export with a mocked pool whose instances hang past the timeout, and asserts the call still completes on time. Verified by hand that removing the timeout argument makes this test hang, confirming it actually catches a regression.
• vp test run apps/desktop/src/backend/DesktopBackendManager.test.ts: 26 passed
• vp run --filter @t3tools/desktop typecheck: clean

---

Model: Claude Sonnet 5. Harness: Claude Code.

---

Note

Medium Risk
Changes desktop quit/shutdown behavior for all pooled backends; bounded wait reduces hang risk but timed-out teardown may still run in the background.

Overview
Fixes quit hangs when a backend pool instance never finishes teardown (e.g. after the window is destroyed first), so Cmd+Q could appear to do nothing until force quit.

Quit finalizer now goes through exported stopAllPoolInstances, which stops every pooled backend concurrently with a 5s timeout per instance.stop—same pattern as DesktopUpdates.ts. After the budget, quit keeps moving instead of waiting forever; slow but healthy shutdown can still finish in the background.

Adds a regression test that calls the real stopAllPoolInstances with a mocked pool whose instances hang past the timeout and asserts the call completes on time.

^{Reviewed by Cursor Bugbot for commit 6187110. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Bound backend shutdown wait to 5 seconds per instance during desktop app quit

• Extracts a new stopAllPoolInstances function in DesktopApp.ts that stops each instance from DesktopBackendPool with a 5-second timeout, running stops concurrently.
• Replaces the inline teardown loop in scopedProgram's finalizer with a call to stopAllPoolInstances, preventing the app from hanging indefinitely on quit if a backend fails to stop.
• Adds a test in DesktopBackendManager.test.ts that simulates hanging teardown and verifies the effect completes after the timeout.

^{Macroscope summarized 6187110.}

Summary by CodeRabbit

• Bug Fixes
  • Improved application shutdown reliability when backend services fail to stop promptly.
  • The app now proceeds with shutdown after a five-second limit instead of waiting indefinitely.
  • Backend cleanup continues in the background and completes when services become available again.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: d60a55fd-9e76-418f-bbf1-a60b60162abc

📥 Commits

Reviewing files that changed from the base of the PR and between c52b8d9 and 44ad0b1.

📒 Files selected for processing (2)

• apps/desktop/src/app/DesktopApp.ts
• apps/desktop/src/backend/DesktopBackendManager.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The desktop app now exposes a shared helper that stops all backend pool instances with five-second timeouts. The shutdown finalizer uses this helper. A test verifies that hung backend teardown does not block quitting.

Changes

Desktop shutdown

Layer / File(s)	Summary
Bounded backend stop flow apps/desktop/src/app/DesktopApp.ts	The app lists all backend pool instances and stops them concurrently with a five-second timeout. The shutdown finalizer calls the shared helper.
Shutdown timeout validation apps/desktop/src/backend/DesktopBackendManager.test.ts	The test verifies that the quit finalizer returns after five seconds while backend teardown remains blocked, then completes teardown after release.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 44ad0

Backend shutdown can no longer indefinitely block desktop quit, including when teardown hangs.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: bounding backend shutdown time during desktop application quit.
Description check	✅ Passed	The description explains the problem, fix, testing, scope, and risk. It does not use the template headings exactly and omits the checklist, but it provides the required information in equivalent secti…
Linked Issues check	✅ Passed	The changes address issue #7598 by applying a 5-second timeout to each backend stop, allowing quit to continue when teardown hangs, updating the quit finalizer, and adding regression coverage.
Out of Scope Changes check	✅ Passed	The changes are limited to desktop backend shutdown behavior and its regression test. They directly support the linked issue and stated objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[macroscopeapp]

Approvability

Verdict: Approved at 6187110

Macroscope's review found this PR approvable — Straightforward bug fix that adds a 5-second timeout to backend shutdown during quit, preventing indefinite hangs. The change extracts existing logic into a named function, adds a timeout parameter, and includes a comprehensive test. Limited scope with clear defensive purpose.

^{You can add or adjust custom eligibility rules. Learn more.}

[shivamhwp]

Note: GPT-6 on behalf of shivam (@shivamhwp).

Please make the shutdown regression wait for both backend finalizers to start, then wait for both to finish after releasing allowTeardown. The shared teardownStarted Deferred only confirms one backend reached teardown, and advancing TestClock by 100 ms does not establish that either finalizer finished. Use per-instance Deferreds or queue notifications for those milestones.

Please also invoke stopAllPoolInstances from an Effect.addFinalizer scope in the regression. That matches the quit path's finalizer context instead of exercising only an ordinary interruptible call.

[ishaanko]

Thanks, both points are addressed in 44ad0b1.

Per-instance milestones. Each backend's process-scope finalizer now offers its instance name to a teardownStarted queue when it begins and to a teardownFinished queue when it ends. The test takes two entries from teardownStarted before it advances the clock, so both backends are proven to have reached teardown. After the quit finalizer returns, it asserts teardownFinished is still empty, releases allowTeardown, and then takes two entries from teardownFinished. No clock advance stands in for completion any more.

Finalizer context. The test now registers stopAllPoolInstances with Effect.addFinalizer inside an Effect.scoped block and lets the scope close run it, which matches how DesktopApp invokes it on quit.

I also rebased onto current main, since the old branch no longer shared history with it. Verified by hand that removing the timeout argument makes the test hang, so it still catches the regression.

Model: Claude Fable 5.1. Harness: Claude Code.