fix(desktop): surface Buzz Term attach failures instead of a blank panel

[Glucksberg]

Summary

When the Term panel fails to attach, it renders nothing — a blank body with a + button that does nothing. TerminalBootstrap.fail() removes the session, sets available = false, and reports the error to console.error. In a production build there is no devtools to read that, and on Windows there is no log file either, so the error the backend produced is simply discarded on the way to the user.

That is the surface #4930 was reported through: the reporter saw a permanently blank Term panel and had nothing to attach to the issue except a Windows Event Log entry. The backend had a precise, actionable error the whole time — CreateProcessW "cmd.exe" in cwd None failed … (os error 2) — and the UI threw it away.

This renders that error in the viewport instead, with a Retry action that clears it and re-runs the auto-create path.

Before / after

Screenshots in the first comment. Both are the same element (.buzz-terminal-substrate) at the same viewport, so they're directly comparable.

Why there is no notice for "no channel selected"

An earlier version of this change also rendered "Select a channel to open a terminal." when the panel had no channel context. That state is not reachable, and shipping the notice would have been a small regression:

• TerminalBootstrap.tsx — the Cmd/Ctrl+J toggle returns early when !context, so the panel cannot be opened without a channel.
• An effect closes the panel when context goes away while it is open.

So the only way to render that notice is the single frame between navigating away from a channel and the effect running. That's a flash during navigation, not a state a user can be in. The existing test a non-channel route closes the panel and ignores the terminal shortcut already asserts this behaviour. The notice is now scoped to the one case that genuinely occurs: !available.

Relationship to #5425

Related, not a duplicate, and they fix different things.

• fix(desktop): make the Windows terminal spawn, close, and inherit PATH (#4930) #5425 (Rust) makes the Windows attach succeed — three stacked backend defects.
• This PR (React) makes an attach failure visible.

Neither subsumes the other. With #5425 merged, a Windows user shouldn't reach the failure path by that route — but any future attach failure, on any platform, is silent again without this change. They can merge in either order; they touch no common files.

Related issue

Related to #4930 — this addresses the "Term panel renders permanently blank" symptom, which #5425 explicitly leaves out of scope. Deliberately not marked Fixes, since the root cause of that issue is the backend spawn failure, not this rendering gap.

Searched for duplicates: no other open PR touches desktop/src/features/terminal.

The issue's remaining item — "the desktop currently writes no log files on Windows" — is not addressed here.

Testing

• Unit (TerminalBootstrap.test.mjs, 10/10): the notice renders with the backend's own error text, and Retry re-attaches after a failure. Full desktop JS suite: 4536/4536.
• E2E screenshot spec (term-empty-states-screenshots.spec.ts, registered in the smoke project): drives the real attach-failure path end to end. The mock bridge doesn't implement terminal_attach, so the panel takes the genuine failure route rather than a stubbed one — the notice, its text, and the Retry button are all asserted before the capture.
• pnpm check (biome, file sizes, px-text, pubkey truncation) and pnpm typecheck clean.

One note on reading the screenshot: the error string in it is the mock bridge's (Unsupported mocked Tauri command: terminal_attach), because that is what fails in an e2e build. On Windows the same slot carries the real CreateProcessW … error. The point of the shot is that whatever the backend said now reaches the user.

[Glucksberg]

Before — the silent panel

Attach fails, the session is removed, available goes false, and the viewport renders nothing. The + button is still there and still does nothing. This is what #4930 was reported through.

After — the failure is the UI

The backend's own error text, plus a Retry that clears it and re-runs the auto-create path.

The error string here is the e2e mock bridge's (Unsupported mocked Tauri command: terminal_attach) — that is the real thing that fails in an e2e build, so the panel takes the genuine failure route rather than a stubbed one. On Windows the same slot carries CreateProcessW "cmd.exe" in cwd None failed … (os error 2).

Both images are .buzz-terminal-substrate captured at the same viewport, so they frame the identical element.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a649d72e26

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Retry the attachment in its original channel

When an attachment fails in channel B, failedAttachRef records only a global boolean. If the user navigates to channel A, which already has a healthy terminal, before clicking Retry, this effect calls createSession() with contextRef.current for A, spawning an unwanted extra shell there while the failed B attachment remains unretried until the user returns to B. Associate the retry with the failed channel/context, or only force creation when the current channel is the one whose attachment failed.

Useful? React with 👍 / 👎.