Skip to content

fix(dashboard): show a calm reconnecting view while a relay Crew window retries - #36430

Merged
bolichen97 merged 2 commits into
mainfrom
fix/relay-calm-reconnecting
Nov 13, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/relay-calm-reconnecting

Conversation

@tim-finnigan

@tim-finnigan tim-finnigan commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A relay Crew window that is still reconnecting on its own shows a calm "Reconnecting…" view instead of red outage styling.

When a remote Crew's connection drops in the desktop app's relay Crew window and the page is retrying, the top bar shows a red pulsing unplugged plug, a red-tinted readout capsule and a red inline "Reconnecting…" notice. Nothing is wrong that the user can fix. The desktop app already says when retrying stops ("currently unavailable" + Check again, #35167) and when access is refused (#35144).

Why it matters

Red tells the user something failed and they should act. During a transient drop the right action is to wait, so the red is alarming and wrong for every relay teammate who hits a network blip or a relay reconnect.

Not a goal

  • Naming the Crew in the view or adding a Crew pill to that window: the page has no way to learn the name today, tracked in #36428.
  • Any change to the relay window's no-preload contract, /api/status, or the desktop app's notices.
  • The plain (non-relay) dashboard's offline styling, and the refused / session-ended / session-expired states in a relay window.

What changed (motivation → approach → change)

The page already knows it is in a relay Crew window (the kiroCrewRelayWindow user-agent marker) and why it is offline (#34372), so the retrying state is readable without a new signal: offline after the first connect, no refusal, no ended session, no expired sign-in. isRelayRetrying in website/src/utils/offlineReason.ts names it and useAppShell (website/src/shell/appShell.tsx) combines it with the transport state.

In that state only:

  • A new RelayReconnectingView (website/src/shell/RelayReconnectingView.tsx, mounted in website/src/App.tsx) covers the content area: a neutral spinner (still under reduced motion), "Reconnecting…" and two muted lines. Theme variables only.
  • What the view covers is inert while it shows: <main> and a docked terminal panel, through the existing hiddenChromeProps, so keystrokes cannot reach a composer the user cannot see. A maximized terminal paints above the view and stays usable. <main> also gets a stacking context while retrying (mainStackingClass in website/src/utils/terminalFullscreen.ts), so its own fixed layers, such as the phone sessions drawer, stay under the view.
  • The top bar (website/src/shell/topbar/shellHeader.tsx) drops the red: a warn-coloured spinner in place of the red plug, no glass-danger tint, and a warn dot with "connecting…" in place of the red ErrorNotice. The phone strip stays hidden there too.
  • The view is a polite live region mounted for the window's whole life, so it announces the drop. The capsule's status span and the focus-mode stand-in read the new gatewayStatusAnnounce, which is blank only in this state, so screen readers hear one announcement, not two.

Three new strings (app.relay_crew_dropped, app.relay_crew_reconnects_on_its_own, app.relay_crew_connecting) in all 12 locale files under website/src/i18n/locales/; en-XA regenerated.

Backwards compatibility

Compatible: only the retrying state in a relay Crew window renders differently; every other connection state, the desktop app's notices and the APIs are unchanged.

Removes nothing: the red notice and tint still render in every state that had them except a relay Crew window's retrying state, where the centre view replaces them.

Tests

  • website/src/test/App.offlinePill.test.tsx: in a relay Crew window, a drop after connect shows the centre view (live region mounted before the drop, spinner with motion-reduce:animate-none), no glass-danger, no error notice, the warn "connecting…" label a blank capsule status and an inert #main-content; reconnecting empties it and clears inert. refused and session_ended keep the danger styling and notice.
  • website/src/utils/terminalFullscreen.test.ts: mainStackingClass isolates while retrying and not otherwise; the App test also asserts isolate on #main-content while retrying.
  • website/src/test/offlineReason.test.ts: isRelayRetrying is true only for a plain drop in a relay window.
  • website/src/test/agentSwitchNotice.surfacePairing.test.ts: the silenced notice and its live region now pair on gatewayStatusAnnounce.

Revert check: with relayRetrying forced to false, the new App test fails and the two failure-state tests still pass.

Proof: not provable -- frontend test (prove.py runs Python only)

Ran locally: 156 related frontend test files (2,111 tests) green, tsc -p tsconfig.app.json, eslint on the changed files, npm run i18n:check.

Manual verification

Rendered the built SPA against the stub router with the relay user agent (Playwright, 2x): retrying in dark, light and at 420 px, plus the refused relay state and a plain dashboard drop as controls. Each scene asserted the centre view, the capsule tint, the notice and the "connecting…" label. Not run in the real desktop relay window.

Screenshots / video

Relay Crew window, retrying (dark):

Relay window retrying, dark

Retrying (light) and at 420 px wide:

Relay window retrying, light

Relay window retrying, narrow

Unchanged controls: a refused relay connection and a plain dashboard drop stay red

Relay refused, unchanged

Plain dashboard offline, unchanged

Related Issues

Closes #36427

Related: #35167, #34372, #34119, #35125, #35144. Follow-up: #36428.

Sibling sweep

Swept: git grep -n "offlineReason|gatewayStatusMsg|glass-danger" -- website/src
Sibling: website/src/components/chat-input/offlinePlaceholder.ts -- not affected -- the composer sits under the centre view while it shows
Sibling: website/src/App.tsx -- changed here

Pattern harvest

Not generalizable: the defect is one surface styling a self-healing state as a failure; the retrying/failed split is specific to the relay window's cause model.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@tim-finnigan tim-finnigan self-assigned this Nov 13, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of e2ac23dd044ee6e88c86ebf46edf629c97d3ed20 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the retrying state is built from signals the page already reads, the change only applies in a relay window, and five screenshots of this revision are attached.

Notes

  • The view's z-40 and the maximized terminal's z-[51] are two separate literals that have to stay in that order. If someone changes either one, the overlay will cover a usable terminal, or a terminal will sit above an inert page, and only the comment would warn them.

[DESIGN-REVIEWED] e2ac23d

Description read

[DESCRIPTION-READ] a2c889379a96ddb94fd771e6dfdcf3c5c87460a445fbd5fdabf047d70c4d1108

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of e2ac23dd044ee6e88c86ebf46edf629c97d3ed20 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Every item addresses the red styling on a self-healing relay retry (#36427). The only extra is a defaulted parameter that no caller relies on.

Notes

  • Item 9 — one consumer, generalized: isRelayRetrying(cause, relayCrewWindow = isRelayCrewWindow()) has 1 non-test caller (grep isRelayRetrying\(: appShell.tsx:227). That caller passes the flag explicitly and has already ANDed relayCrewWindow && itself, so the default and the re-check never decide anything. Subtraction: drop the relayCrewWindow parameter and its default, and keep only the cause checks.

What this change ships

Inventory (9 items) — 8 justified

Intent: a relay Crew window teammate waiting out a transient drop sees a calm "reconnecting" state, not an outage alarm — FIX.

  1. Relay window retrying: a centre "Reconnecting…" view covers the content area — justified
  2. Top-bar plug turns from a red pulsing unplug into a warn-coloured spinner while retrying — justified
  3. Readout capsule loses its red glass-danger tint while retrying — justified
  4. Red inline notice and the phone strip are replaced by a warn dot and "connecting…" — justified
  5. Main content and the docked terminal become inert under the view — justified
  6. Main gets a stacking context while retrying so its drawers stay under the view — justified
  7. Screen readers hear one announcement (the view), and the capsule and focus stand-in stay quiet — justified
  8. Focus returns to the composer when the connection comes back — undeclared, rides along (repairs the focus loss that item 5 causes)
  9. New exported isRelayRetrying helper and mainStackingClass relayRetrying option — one consumer, generalized

[FIRST-PRINCIPLES-REVIEWED] e2ac23d

Description read

[DESCRIPTION-READ] bb157a2daa8086d7af390e058077faadaff29df8b31dc9da6b5d05c703c474d0

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of e2ac23dd044ee6e88c86ebf46edf629c97d3ed20 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks. The blind reader understood the reconnecting view correctly and with confidence ("fixing it by itself… sure… I would just wait"), and screenshots cover every changed control in dark, light and 420 px.

Notes

  • The top bar's "connecting…" next to the centre view's "Reconnecting…" read to the blind reader as "the same thing said twice". Use the same word in both places: change app.relay_crew_connecting to "reconnecting…".
  • On the plug-with-spinner icon in the top bar, the blind reader said "no idea what clicking does… I can't tell what they control". The warn dot and the label already say the connection state, so add a tooltip or accessible name to the plug icon, such as "Reconnecting to Crew".

[UX-REVIEWED] e2ac23d

Description read

[DESCRIPTION-READ] 4c443ca0799debf352c10825151babdced3039ed06a3388160515d626776e708

That sha256 names everything this verdict read: the PR description, plus the 8 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed e2ac23dd044ee6e88c86ebf46edf629c97d3ed20 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] e2ac23d

Verdict parsed from the review's SHA-scoped output markers for commit e2ac23dd044ee6e88c86ebf46edf629c97d3ed20.

False positive or not applicable? A repository writer can comment:
/ai-review override fable e2ac23dd044ee6e88c86ebf46edf629c97d3ed20 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of e2ac23dd044ee6e88c86ebf46edf629c97d3ed20 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e2ac23d

False positive or not applicable? A repository writer can comment:
/ai-review override gpt e2ac23dd044ee6e88c86ebf46edf629c97d3ed20 false-positive: <reason, 20 to 500 characters>

@tim-finnigan
tim-finnigan force-pushed the fix/relay-calm-reconnecting branch from cd44794 to 15a54a8 Compare November 13, 2026 05:56
@tim-finnigan

tim-finnigan commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author

target=fable span=18e45ae36123 disposition=fixed sha=15a54a88bead

Fixed in 15a54a8: <main id="main-content"> gets hiddenChromeProps(relayRetrying) (inert + aria-hidden, the idiom the header and rail already use), so the covered composer leaves the focus order while the reconnecting view shows.
A docked terminal panel under the view is inert too; a maximized one (absolute inset-0 z-[51], BottomTerminalPanel.tsx) paints above the view's z-40, so it stays usable.
Regression: App.offlinePill.test.tsx asserts #main-content is inert while retrying and not after reconnect; it fails with the <main> spread removed.
self-added: yes
mechanism: inert on content covered by the relay reconnecting overlay

@tim-finnigan
tim-finnigan force-pushed the fix/relay-calm-reconnecting branch from 15a54a8 to 090947e Compare November 13, 2026 06:58
@tim-finnigan

tim-finnigan commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author

target=gpt disposition=fixed sha=090947e9f7ba

  • Chat layers obscure the reconnecting view (website/src/shell/RelayReconnectingView.tsx:22)

Fixed in 090947e: mainStackingClass (website/src/utils/terminalFullscreen.ts) also returns isolate while relayRetrying, so fixed layers inside <main> (the phone sessions drawer at z-50, its scrim at z-[46]) stack under the z-40 reconnecting view instead of over it.
The maximized-terminal case is unchanged; isolating an inert, covered <main> traps nothing the user can reach.
Regression: terminalFullscreen.test.ts covers retrying true/false, and App.offlinePill.test.tsx asserts isolate on #main-content while retrying and not after reconnect; both fail with the production change reverted.
self-added: yes
mechanism: stacking context on

while the relay reconnecting view covers it

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 13, 2026
@tim-finnigan
tim-finnigan force-pushed the fix/relay-calm-reconnecting branch from 090947e to 9352e90 Compare November 13, 2026 16:09
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 13, 2026
The reconnecting view makes <main> and the docked terminal inert, which
drops the focused composer to <body>. Remember the focused element as the
retry starts and focus it again on reconnect, unless the user focused
something else meanwhile.
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 13, 2026
@tim-finnigan
tim-finnigan marked this pull request as ready for review November 13, 2026 19:22
@tim-finnigan
tim-finnigan requested review from a team and KiroCrewCaptain as code owners November 13, 2026 19:22
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 13, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I read the whole diff, including all 14 locale files and the tests. This is a UI-only change, and it looks good to me:

  • isRelayRetrying only treats a plain drop in a relay Crew window as retrying. refused and session_ended keep the danger styling and their own text, and the tests pin both.
  • While retrying, <main> and the docked terminal are inert and isolated under the new view, and focus is given back on reconnect unless the user moved it. A maximized terminal is left alone, because it paints above the view.
  • Exactly one live region speaks the state. gatewayStatusAnnounce stays blank only while the centre view is active.
  • Spinners respect motion-reduce. Each locale adds the same three keys.

There is no regex, no new refusal and no change to the connection itself, and CI is green.

@bolichen97
bolichen97 merged commit 0590215 into main Nov 13, 2026
100 checks passed
@bolichen97
bolichen97 deleted the fix/relay-calm-reconnecting branch November 13, 2026 20:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Relay Crew window: show a calm reconnecting view while it retries, not the red outage styling

2 participants