fix(desktop): recover stranded session windows when resume fails

[austinpickett]

Problem

Opening a session in a new window (or any routed resume) could latch the thread loader on "session" forever — the reported "I've tried to load a session in a new window and even when I took a nap it still didn't load; it stays stuck loading" bug. The spinner has no terminal/error state and no recovery path once a resume fails.

Root cause (two compounding bugs)

1. The REST fallback wasn't isolated. In use-session-actions.ts, resumeSession's catch ran the REST transcript fallback outside its own try:

} catch (err) {
  if (!isCurrentResume()) return
  const fallback = await getSessionMessages(...)   // ← not wrapped
  setMessages(...)
} finally {
  // only clears busy — NOT the loader
}

When session.resume rejected and getSessionMessages also threw (the common case on a wedged/unreachable backend), the throw skipped setMessages and left activeSessionId null with an empty transcript — exactly the state the loader gates on (loadingSession = messagesEmpty && !activeSessionId, chat/index.tsx:318).

2. The self-heal could never re-fire. use-route-resume's stuckOnRoutedSession trigger is gated on routedSessionId !== selectedStoredSessionIdRef.current, but resumeSession sets selectedStoredSessionIdRef.current = storedSessionId synchronously at entry, before it can fail. So after a failed resume the ref already matches the route → trigger is false. On an idle, already-open window pathnameChanged and gatewayBecameOpen also can't fire. The effect has no timer, so leaving it idle — even for hours — never retries.

The user's degraded backend (disabled provider key → HTTP 401, a 27-min runaway generation, intermittent DNS failures) is what triggered the failed resume; the frontend dead-end is what made it permanent.

Fix

• Wrap the REST fallback in its own try so a fallback failure can't strand the loader.
• Add $resumeFailedSessionId (store atom): armed on terminal resume failure, cleared at the next resume's entry, left clear on success.
• Bounded backoff auto-retry in use-route-resume (4 attempts, 1s→8s cap) that re-resumes while the routed session matches the failure flag, with a fire-time liveness recheck so a recovered session isn't double-resumed, and a hard cap so a genuinely dead backend can't hot-loop.

Verification

Reproduced first against the live worktree (per repo convention), then fixed:

• npm run typecheck — clean
• use-route-resume.test.tsx — +4 tests (retry fires on backoff; no retry for non-routed failure; skips if recovered before timer fires; caps at MAX). Original 4 still pass.
• use-session-actions.test.tsx — +3 tests (flag armed when both RPC + REST fail; resume doesn't throw out of the fallback; flag cleared on success). Original 3 still pass.
• Full vitest UI suite: the only src/ failures (6) are pre-existing on main (Windows path separators, env-dependent settings tests, a gateway-boot timing test) — confirmed by git stash + re-run on the clean tree.

Files

• store/session.ts — $resumeFailedSessionId atom + setter
• use-session-actions.ts — isolate REST fallback, arm/clear the flag
• use-route-resume.ts — bounded retry effect
• desktop-controller.tsx — wire the atom into the hook
• *.test.tsx — regression coverage

[github-actions]

🔎 Lint report: fix/desktop-stuck-session-window-resume vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 10992 on HEAD, 10990 on base (🆕 +2)

🆕 New issues (2):

Rule	Count
unresolved-attribute	2

First entries

run_agent.py:2941: [unresolved-attribute] unresolved-attribute: Object of type `Self@get_credits_spent_micros` has no attribute `_credits_session_start_micros`
tests/run_agent/test_credits_notices_toggle.py:76: [unresolved-attribute] unresolved-attribute: Unresolved attribute `_credits_session_start_micros` on type `AIAgent`

✅ Fixed issues (1):

Rule	Count
invalid-assignment	1

First entries

tests/run_agent/test_credits_notices_toggle.py:76: [invalid-assignment] invalid-assignment: Object of type `None` is not assignable to attribute `_credits_session_start_micros` of type `int`

Unchanged: 5791 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

[alt-glitch]

Related, not duplicate. This fixes the thread LOADER latching on "session" forever when both session.resume and the REST getSessionMessages fallback throw (REST fallback not isolated + self-heal trigger gated on a ref set synchronously at entry, so it never re-fires). That is a different code path and remedy ($resumeFailedSessionId atom + bounded backoff retry) from the composer-busy-stuck-on-resume fixes #41907 / #45729 (which clear the optimistic setBusy(true) in resumeSession). Same file (use-session-actions.ts), different bug. Related to #41901 (the reported resume issue), #41907, #45729.

[OutThisLife]

Reviewed the diff (didn't check out the branch). The root-cause writeup is excellent and correct — the unwrapped await getSessionMessages inside resumeSession's catch is a genuine strand-the-loader path, and the selectedStoredSessionIdRef-synced-at-entry observation explaining why the existing self-heal can't re-fire is spot on. Wrapping the REST fallback in its own try is clearly right. A few things on the recovery layer that I think are worth addressing before merge:

1. (med/high) The failure latch is armed even when the REST fallback succeeds. In use-session-actions.ts, setResumeFailedSessionId(storedSessionId) sits after the fallback try/catch, so it fires whenever the resume RPC rejects — including the case where getSessionMessages succeeded and painted the transcript:

try {
  const fallback = await getSessionMessages(...)
  if (!isCurrentResume()) return
  setMessages(...)            // history is now visible
} catch { /* both failed */ }

if (isCurrentResume()) {
  setResumeFailedSessionId(storedSessionId)   // armed regardless
}

This contradicts the $resumeFailedSessionId atom's own documented contract ("the gateway RPC rejected AND the REST transcript fallback also failed ... empty transcript"). The concrete consequence: a window that did recover its history via REST will still auto-retry, and once the 4 attempts exhaust, $resumeExhaustedSessionId is set → the absolute inset-0 z-10 error overlay in chat/index.tsx paints over a transcript the user could previously read, and showChatBar is hidden. That's a regression vs. today's fallback-success behavior. Either arm only when both paths failed (move the setResumeFailedSessionId into the catch, or gate it on messagesEmpty), or make the exhausted overlay respect messagesEmpty so it never clobbers visible history. The new use-session-actions tests cover "both RPC + REST fail" but not "RPC fails, REST succeeds," so this slips through.

2. (med) The "manual Retry / reconnect / reselect gives the counter a clean cycle" claim doesn't actually hold for the same session. retryAttemptRef is only reset in the retrySessionIdRef.current !== routedSessionId branch — i.e. when the route changes to a different session. On a manual onRetryResume (or a gatewayBecameOpen reconnect) for the same stranded session, resumeSession clears the atoms but retrySessionIdRef.current still equals routedSessionId, so the counter stays pinned at MAX_RESUME_RETRIES. Trace: clear flag → effect re-runs !stranded, no reset → resume fails → flag re-armed → attempt (4) >= MAX → setResumeExhaustedSessionId immediately. So post-exhaustion the user gets exactly one attempt per click, never a renewed backoff cycle, despite the comments in both store/session.ts and use-session-actions.ts promising a fresh cycle. Suggest resetting retryAttemptRef when the latch is cleared for the current session (or keying the reset on the resumeFailedSessionId null→value transition rather than only on route change).

3. (low) Unrelated dep changes during a backoff window can burn retry attempts. The effect increments retryAttemptRef.current synchronously every time it runs while stranded, but the deps include gatewayState, currentView, and resumeSession. If any of those change during the 1s–8s wait (e.g. a transient gateway state flip, or resumeSession isn't referentially stable), the cleanup clears the pending timer and the re-run increments the counter again without an actual resume having fired — so a flapping backend could reach MAX in a couple of re-renders with fewer than 4 real attempts. Consider only advancing the counter when the timer actually dispatches a resume.

4. (nit) store/session.ts and use-session-actions.ts carry a few blank-line-only insertions (workspaceCwdKey, ensureDefaultWorkspaceCwd, mergeSessionPage, the resumePromise block) unrelated to this fix — worth dropping to keep the diff tight.

Test coverage is otherwise good and behavior-based (not change-detector), and the i18n strings are complete across all five locale files. #1 is the one I'd consider blocking; #2/#3 are correctness-of-the-recovery-loop and at minimum the comments should match the implemented behavior.

[OutThisLife]

Re-reviewing against my earlier comments — v2 addresses all of them, each with a dedicated regression test:

1. (was med/high) The failure latch is no longer armed when the REST fallback paints history. Arming now happens only under isCurrentResume() && $messages.get().length === 0, matching $resumeFailedSessionId's documented contract, so a window that recovered via REST won't auto-retry and then blank a readable transcript behind the exhausted overlay. Covered by does NOT arm the failure latch when the resume RPC fails but the REST fallback paints history.
2. (was med) The retry counter now resets on the exhausted-latch armed→cleared edge (prevResumeExhaustedRef), so a manual Retry / reconnect on the same stranded session gets a fresh bounded cycle instead of one-shot-then-immediately-re-arm. Covered by resets the retry counter for a fresh backoff cycle when the exhausted latch clears (manual retry, same session).
3. (was low) The attempt counter is consumed only when the timer actually dispatches a resume, so unrelated dep changes during the 1s–8s backoff window can't burn attempts. Covered by does not burn retry attempts on unrelated re-renders during the backoff window.
4. (was nit) The unrelated blank-line insertions are gone — diff is tight.

The core fix — isolating the REST fallback in its own try so a fallback failure can't strand the loader — is correct, the i18n strings are complete across all five locales, and the tests are behavior-based rather than change-detectors. CI green.

LGTM, approving.