Repository navigation
fix(dashboard): show one calm offline state when a relay Crew's host or the local gateway stops - #38103
Conversation
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: each item traces to the outage reported in #38100, the moved symbols are needed for module boundaries, and the reconnect refetch uses the same predicate as What this change shipsInventory (10 items) — 10 justifiedIntent: when a relay Crew's host or the local gateway stops, the user sees one calm offline state instead of a red error in every panel. FIX.
The change has more than 10 items. Left out: the Playwright capture script, which follows the repo's existing [FIRST-PRINCIPLES-REVIEWED] 2a8e92c Description read[DESCRIPTION-READ] 74172338ce4d6f2eaa77b450f414585f72d8f09f4864195db1a21033b56a2078 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns: one shared cover over the existing connected/offline state fixes the common cause instead of patching each panel, and direct and non-loopback dashboards behave as before. Notes
[DESIGN-REVIEWED] 2a8e92c Description read[DESCRIPTION-READ] 3ff41d6d5106fa1c45010ab0fc590ffa94925ac6a216123fe7c4b5ae3fdc237b 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 |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS No blocker: the screenshots show every state this PR adds, and the blind reader read the new host-offline cover's message correctly. The two notes below come from where that reader got stuck. Notes
[UX-REVIEWED] 2a8e92c Description read[DESCRIPTION-READ] 41a23cb6454e2524afd78a0058cdec8597b3f1cd7904205f91cae93520503146 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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)GPT 6.1 flagged blocking issues on This comment is updated in place on each push. Review detailsBLOCKING -- website/src/shell/useHostOfflineCover.ts:19 -- Cancelling a restart leaves the offline cover suppressed
Adjudication (Opus 5.5) — is blocking on each finding proportionate?F1 is LOW harm. Four things have to coincide for it to happen:
What the user sees is that the offline cover stays away for at most the 15-minute TTL ( False positive or not applicable? A repository writer can comment: |
4c1e784 to
e998424
Compare
e998424 to
4120593
Compare
…or the local gateway stops A relay Crew window whose host stopped showed the red "Relay refused the connection" notice and a red error in every panel, and the "currently unavailable" notice came late or never. The owner's own dashboard on this machine showed a NetworkError in every panel. - The relay closes viewer sockets 4404 crew_not_connected once the host connection ends. Read that as an outage still being retried, so the window gets its calm reconnecting view. 4409, 4410, 4429 and the rest of the relay block stay refusals. - The window no longer reads a WebSocket upgrade's 101 as the host answering (the relay accepts the upgrade, then closes it 4404), which reset the two-minute cap on every socket attempt. A /api/status 503 with x-kiro-relay-error: crew_not_connected now ends the wait after 30 s, and any other 2xx read clears it. - One gate, offlineCover, covers the content area while the connection is down: the relay window's reconnecting view, or a new "Kiro Crew isn't running on this machine" view on a loopback dashboard. The panels under it are hidden and inert; while connected they show as before. - The reconnect catch-up refetches every query that failed with no value, so the panels come back with the connection. Closes #38100
4120593 to
2a8e92c
Compare
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own. The PR replaces the per-panel red errors with one calm offline view, covering two cases: a relay Crew window whose host has stopped, and a loopback dashboard whose gateway has stopped. The code matches the description. 4404 is the only close code that moves from refusal to outage. The host cover only shows after the 5 s grace and stays off while a restart this tab asked for is pending; the desktop app's own restart paints its loading screen, so the cover doesn't show there. On the desktop relay-window side, the relay's error header is trusted, and a Crew can't forge it because the relay drops a Crew's x-kiro-relay-* headers. A socket's 101 no longer resets the unreachable count, and /api/status and other non-cached 2xx reads still prove the host is there. The reconnect refetch only touches queries that failed and never held a value, so drafts are safe. Each behaviour change has a test that fails without it, and CI is green. The rest (desktop main-window wording, the rare case where the restart marker holds the cover back, layer stacking order, the shorter notice timing) is minor and listed in the non-blocking notes. Tier: 2, held for a person: 39 files, more than 20. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
This review checked head 2a8e92c for correctness, scope and test evidence. It confirmed that restartGateway keeps its 409 confirm-then-force flow, and that 4409 and 4410 still show the refused wording. The relay window no longer counts an accepted 101 as proof the host answered, and moved helpers keep their old import paths. The reviewers re-ran the PR's revert-to-red checks and each one held. Nothing blocks.
Done well: one shared offline gate fixes the cause for every panel at once, while connected panels and remote dashboards behave as before.
The design is signed off under the standing maintainer sign-off for changes by team members.
Optional:
- relay-crew-reachability.js:36: the 30 s crew_not_connected bound is shorter than the host's relay reconnect backoff (up to 60 s with jitter), so a short host network blip can land on the manual "Check again" notice. Consider a longer bound or a light re-check while the notice shows.
- gatewayRestart.ts: the restart-pending note duplicates the existing UPDATE_RESTART_LATCH that the gateway's own
restartingframe already sets. Reading that latch would remove the declined-confirm suppression case. - updates.ts:40-53 and bundleReload.ts:54-60: no test fails if the restart note or clear lines are removed. Assertions on gatewayRestartPendingMs() in ApiClient.updates.confirm.test.ts would pin them.
Problem / Motivation
Goal: When a relay Crew's host or the local gateway stops, the user sees one calm offline state (and, in the relay window, the "currently unavailable" notice soon after) instead of a red error in every panel.
Stopping the host of a relay Crew (Nightly 0.14.0-nightly.20261116t061021, gamma relay) made the desktop relay Crew window say "Relay refused the connection — retrying" and repeat "The Crew is not connected to the relay." in Sessions, over the composer and in the guide popup, all red, while it kept fetching. The owner's own dashboard on
localhostshowed "NetworkError when attempting to fetch resource." in folders, board columns, folder order, the Changes banner and Sessions. Causes, with line references, are in #38100.Why it matters
Every relay teammate whose host stops, and every owner whose gateway stops or restarts, gets a screen full of red errors that all say the same thing, and the relay window never tells them the Crew is gone.
Not a goal
What changed (motivation → approach → change)
The relay closes every viewer socket 4404
crew_not_connectedonce a host connection ends, accepts later upgrades and closes them the same way, and answers HTTP with503andx-kiro-relay-error: crew_not_connected(relay protocol v1, sections 6.2 and 7). The page read 4404 as a refusal, and the desktop window read each accepted upgrade's 101 as the host answering, which reset its two-minute cap on every socket attempt.relayClose.ts: 4404 is an outage still being retried, so the relay window keeps its calm reconnecting view. 4409, 4410, 4429 and the rest of the block stay refusals.relay-crew-window.jsandrelay-crew-reachability.js: a 101 counts for nothing, any other 2xx read clears the count, and a retry answeredcrew_not_connectedends the wait afterHOST_GONE_AFTER_MS(30 s, a new constant; no existing one meant this) and at least 5 such answers. The window then shows the existing unavailable notice, which unloads the page and so stops its retries; Check again reloads it. Renewal'sCREW_OFFLINEstill shows it too.offlineReason.tsofflineCover: one gate on the existing connected/offline state. It covers the content area with the relay window's reconnecting view, or, on a loopback dashboard with the gateway gone, a new "The gateway isn't running on this machine. Start it from a terminal with kirocrew gateway. This page reconnects when it's back. Your sessions are kept." view (website/src/shell/RelayReconnectingView.tsx,cover="host", no Back to Local button). It names the start command because the restart command refuses a stopped service.website/src/shell/appShell.tsxcomputes it andwebsite/src/App.tsxmakes<main>and the docked terminal inert under it, and wraps<main>'s children in the existingOffScreenOverlayScope, so the layers they portal out of<main>(the guide's error pill, a link preview, a page's Modal) leave the screen with it and come back as they were. While connected the panels and their real errors show as before. 3 newapp.host_offline_*strings in every file underwebsite/src/i18n/locales/.isLoopbackHostmoves unchanged from the Browser panel'swebPreviewPanelUrl.tstowebsite/src/lib/loopbackHost.ts, soofflineReason.tsno longer imports a panel owner (the panel's module-boundary test).website/src/shell/useHostOfflineCover.ts: the host view waits outQUIET_RECONNECT_GRACE_MS(the relay path's 5 s, moved unchanged toutils/reconnectBackoff.tsso the shell need not import a socket owner), and stays off while a restart this tab asked for is pending.website/src/lib/gatewayRestart.tsrecords it:api.restartGateway(api/client/updates.ts) notes it before posting and drops it on a refusal or a declined confirm, an update'srestartingstep notes it,failed/error/doneand the next connect clear it, and it lapses afterUPDATE_RESTART_LATCH_TTL_MS(moved unchanged beside it).website/src/components/overlayRoot.tsx: a nestedOffScreenOverlayScopeis off screen whenever its parent is, so a Sessions sidebar menu closes under the cover;GlobalOverlayScoperesets that signal, so a dialog's pickers keep working.serverState.ts: the reconnect catch-up refetches every query that failed and never held a value, on every client, so the covered panels come back with the connection. A query that kept its value is left alone (an unsaved draft may sit on it), the same rule as the auth recovery inapi/client.ts.Backwards compatibility
Compatible: a direct, non-loopback or Kiro Mobile dashboard behaves as today, and a relay refusal other than 4404 keeps its wording and colour.
Removes nothing: no key, route or capability is removed; 4404 moves from the refused wording to the reconnecting one.
Tests
relayClose.test.ts: 4404 isoffline, 4409 and 4410 stayrefused.offlineReason.test.ts:offlineCovergives the relay window the calm view after a 4404, keeps a refusal and an ended session red, covers a loopback host, and covers nothing while connected, connecting or signed out.App.offlinePill.test.tsx: on a host drop nothing covers the page inside the grace; after it the "gateway isn't running" view shows and nameskirocrew gateway,mainis inert and hidden, a layer the page portals out ofmainis gone and returns on reconnect, the top bar keeps "Gateway offline — reconnecting", and reconnecting lifts the cover; a relay reason gets no host cover.useHostOfflineCover.test.ts: a drop that reconnects inside the grace shows no cover, one that outlasts it shows the host view, a pending restart holds it off past the grace until the next connect, and the relay cover passes straight through.overlayRoot.test.tsx: a menu in a nested scope closes, and reads hidden, when only the outer scope goes off screen; one inside aGlobalOverlayScopedialog stays open.electron/test/relay-crew-window.test.js,relay-crew-reachability.test.js: an accepted-then-closed socket no longer clears the cap;crew_not_connectedanswers trip the notice at the 30 s bound and not before; a plain 503 waits out the full cap.serverState.reconnectErrors.test.ts: a failed read with no value refetches on reconnect, one that kept its value does not.useWebSocket.frameTrace.test.ts: the reconnect trace gains the one invalidation.Ran locally: electron
relay-crew-*(112 pass), vitestsrc/test/App.*,src/hooks,src/shell,src/utils,useWebSocket*,offlineReason,WebPreviewPanel*,overlayRoot, the restart callers' specs (405 files, 5594 pass),tsc -p tsconfig.json, eslint on changed files,lint:i18n,i18n:check. With the production hunks reverted, the two new window tests and the new reachability test fail; with theOffScreenOverlayScopewrapper reverted, the App host-drop test fails on the portaled layer; without the grace the in-grace, pending-restart and App host-drop tests fail; without the pending check the pending-restart test fails; without the parent signal the nested-scope test fails; without theGlobalOverlayScopereset the dialog test fails.Proof: not provable -- frontend test (prove.py runs Python only)
Manual verification
Rendered the built SPA against the stub router with
scripts/capture-38100-offline-cover.mjs(Playwright Chromium, 2x): the socket closed 4404 with the relay window's user agent, closed 4410 as the control, and dropped on 127.0.0.1 with every later/apiread failing. Each scene asserts its view, the top-bar notice andmaininert; the host scene waits for its view to appear after the grace. Not run in a real Electron relay window against a stopped host: Electron is not installed in this worktree. Assumed, not observed:webRequest.onCompletedreports a WebSocket upgrade as 101 and carriesresponseHeadersfor a fetch.Screenshots / video
Relay Crew window, host gone (socket closed 4404): the calm reconnecting view, no red.
Owner's dashboard on this machine, gateway stopped: one view over the panels that names the command to start it; the top bar keeps its notice.
The existing unavailable notice the window now reaches after 30 s of
crew_not_connected(unchanged, rendered fromrelay-crew-notice.htmlwith the textrelay-crew-notice.jsgives it):Control and light theme
A real refusal (4410, the host turned access off) keeps the red notice:
Related Issues
Closes #38100
Part of #34355 (Part 2, quiet panels while offline, for these two cases). Related: #35125, #35167, #36430.
Sibling sweep
Swept: git grep -n "4400|RELAY_BLOCK|statusCode >= 400|watch.ok" -- website/src website/electron
Sibling: website/src/hooks/websocket/relayClose.ts -- changed here
Sibling: website/electron/relay-crew-window.js -- changed here
Sibling: website/src/hooks/useDashboardHealthProbe.ts -- not affected -- its 503 already reads as keep polling, which is the retry the cover now shows
Pattern harvest
Rule candidate: review-prompt
Pattern: "a transport success code (101, 200 on an upgrade) treated as proof the far end answered, when a proxy accepts first and refuses after"
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)