Skip to content

fix(dashboard): show one calm offline state when a relay Crew's host or the local gateway stops - #38103

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/relay-host-gone-offline-state
Nov 17, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/relay-host-gone-offline-state

Conversation

@tim-finnigan

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

Copy link
Copy Markdown
Contributor

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 localhost showed "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_connected once a host connection ends, accepts later upgrades and closes them the same way, and answers HTTP with 503 and x-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.js and relay-crew-reachability.js: a 101 counts for nothing, any other 2xx read clears the count, and a retry answered crew_not_connected ends the wait after HOST_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's CREW_OFFLINE still shows it too.
  • offlineReason.ts offlineCover: 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.tsx computes it and website/src/App.tsx makes <main> and the docked terminal inert under it, and wraps <main>'s children in the existing OffScreenOverlayScope, 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 new app.host_offline_* strings in every file under website/src/i18n/locales/. isLoopbackHost moves unchanged from the Browser panel's webPreviewPanelUrl.ts to website/src/lib/loopbackHost.ts, so offlineReason.ts no longer imports a panel owner (the panel's module-boundary test).
  • website/src/shell/useHostOfflineCover.ts: the host view waits out QUIET_RECONNECT_GRACE_MS (the relay path's 5 s, moved unchanged to utils/reconnectBackoff.ts so the shell need not import a socket owner), and stays off while a restart this tab asked for is pending. website/src/lib/gatewayRestart.ts records it: api.restartGateway (api/client/updates.ts) notes it before posting and drops it on a refusal or a declined confirm, an update's restarting step notes it, failed/error/done and the next connect clear it, and it lapses after UPDATE_RESTART_LATCH_TTL_MS (moved unchanged beside it).
  • website/src/components/overlayRoot.tsx: a nested OffScreenOverlayScope is off screen whenever its parent is, so a Sessions sidebar menu closes under the cover; GlobalOverlayScope resets 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 in api/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 is offline, 4409 and 4410 stay refused.
  • offlineReason.test.ts: offlineCover gives 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 names kirocrew gateway, main is inert and hidden, a layer the page portals out of main is 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 a GlobalOverlayScope dialog 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_connected answers 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), vitest src/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 the OffScreenOverlayScope wrapper 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 the GlobalOverlayScope reset 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 /api read failing. Each scene asserts its view, the top-bar notice and main inert; 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.onCompleted reports a WebSocket upgrade as 101 and carries responseHeaders for a fetch.

Screenshots / video

Relay Crew window, host gone (socket closed 4404): the calm reconnecting view, no red.

Relay window, host gone

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.

Host offline

The existing unavailable notice the window now reaches after 30 s of crew_not_connected (unchanged, rendered from relay-crew-notice.html with the text relay-crew-notice.js gives it):

Unavailable notice, dark

Control and light theme

A real refusal (4410, the host turned access off) keeps the red notice:

Relay refused, unchanged

Unavailable notice, light

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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 2a8e92c167233eb8525ceb419e4fcb9995465689 — 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: 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 api/client.ts.

What this change ships

Inventory (10 items) — 10 justified

Intent: 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.

  1. Relay window: a 4404 close shows the calm reconnecting view, not the red "refused" notice — justified
  2. Desktop relay window shows "currently unavailable" after about 30 s of crew_not_connected, not after 2 min — justified
  3. An accepted socket upgrade (101) no longer resets the unreachable count; other fresh 2xx reads do — justified
  4. Loopback dashboard: after 5 s offline, a "gateway isn't running — kirocrew gateway" view covers the content area — justified
  5. <main> and the docked terminal go inert under the cover, and the layers they portal out leave the screen with them — justified
  6. Menus in a nested off-screen scope close when the outer scope goes; dialog pickers keep working — justified
  7. The host cover stays off while a restart or update this tab asked for is pending (at most 15 min) — justified
  8. On reconnect, queries that failed and never held a value refetch in every client — justified
  9. Three new app.host_offline_* strings in every locale — justified
  10. isLoopbackHost, QUIET_RECONNECT_GRACE_MS and the restart-latch TTL move unchanged to shared modules — justified

The change has more than 10 items. Left out: the Playwright capture script, which follows the repo's existing capture-*.mjs pattern.

[FIRST-PRINCIPLES-REVIEWED] 2a8e92c

Description read

[DESCRIPTION-READ] 74172338ce4d6f2eaa77b450f414585f72d8f09f4864195db1a21033b56a2078

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 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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

  • gatewayRestartPendingMs keeps the host cover off for up to 15 minutes if a restart the tab asked for never comes back. The code itself marks this as a shortcut, so a status probe is the follow-up if that wait shows up in practice.
  • website/scripts/capture-38100-offline-cover.mjs is a one-off evidence script named after an issue. Unless something runs it again, it would fit better outside the shipped scripts/ tree.

[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 .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 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

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

  • RelayReconnectingView.tsx: the command {{command}} in app.host_offline_reconnects is plain muted text. The blind reader "can barely tell it's a command" (shot-02). Show kirocrew gateway as inline <code> with a copy button, so the one thing the user must type is easy to find and copy.
  • The host cover shows the same spinning Loader2 as the relay view, but its copy asks the user to act. The reader asked "is it waiting, or is it stuck?" (shot-02). On cover="host", replace the spinner with a static icon such as a plug-off, or put the spinner next to "This page reconnects when it's back" so it clearly means waiting.

[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 .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 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 2a8e92c

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

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

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 6.1 flagged blocking issues on 2a8e92c167233eb8525ceb419e4fcb9995465689; Opus 5.5 adjudication downgraded every one of them. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

This comment is updated in place on each push.

Review details

BLOCKING -- website/src/shell/useHostOfflineCover.ts:19 -- Cancelling a restart leaves the offline cover suppressed

if (pending > 0) { timer = setTimeout(check, pending); return }
Trigger: On a loopback dashboard, Settings → Restart receives 409 work_in_flight; the gateway stops while the confirmation remains open. After the five-second grace schedules this timer, the user cancels and restartGateway() calls clearGatewayRestart().
Outcome: Clearing the latch neither reschedules the timer nor changes the effect’s [cover] dependency. The offline view and gateway-start instructions remain hidden until the original 15-minute deadline, leaving per-panel errors exposed.
Anchor: defect
Fix: Subscribe the hook to restart-latch changes and recheck immediately when the latch clears after the reconnect grace.

[BLOCK-MERGE-DOWNGRADED] 2a8e92c
[GPT-REVIEWED] 2a8e92c

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 is LOW harm. Four things have to coincide for it to happen:

  • restartGateway notes the latch (website/src/api/client/updates.ts:39) and the gateway answers 409.
  • The gateway stops by itself while the confirm dialog (updates.ts:44) is still open.
  • The 5-second grace has already fired and re-armed the timer (website/src/shell/useHostOfflineCover.ts:19).
  • The user then declines, which clears the latch (updates.ts:53).

What the user sees is that the offline cover stays away for at most the 15-minute TTL (website/src/lib/gatewayRestart.ts:26). It is not silent: the per-panel errors stay on screen, and a reconnect (useHostOfflineCover.ts:13) or a page reload, which resets the module-level requestedAt (gatewayRestart.ts:10), clears it. The file already accepts this same 15-minute bound as a documented shortcut for a restart that never comes back (gatewayRestart.ts:21-23). The fix would need a new subscribe/notify mechanism on the latch, built only for this one coincidence, and that costs more than a rare cosmetic delay that clears itself.

[ADJUDICATION] 2a8e92c167233eb8525ceb419e4fcb9995465689 total=1 uphold=0 downgrade=1
DOWNGRADE F1 website/src/shell/useHostOfflineCover.ts:19 reason=disproportionate-remedy
[GPT-ADJUDICATED] 2a8e92c167233eb8525ceb419e4fcb9995465689

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 16, 2026
@tim-finnigan
tim-finnigan force-pushed the fix/relay-host-gone-offline-state branch from 4c1e784 to e998424 Compare November 17, 2026 01:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 17, 2026
@tim-finnigan
tim-finnigan force-pushed the fix/relay-host-gone-offline-state branch from e998424 to 4120593 Compare November 17, 2026 03:38
@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 17, 2026
…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
@tim-finnigan
tim-finnigan force-pushed the fix/relay-host-gone-offline-state branch from 4120593 to 2a8e92c Compare November 17, 2026 04:00
@iamwhatever
iamwhatever marked this pull request as ready for review November 17, 2026 05:37
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 17, 2026 05:37
@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 17, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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 2a8e92c167 · 820 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 17, 2026 06:52

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

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 restarting frame 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.

@KiroCrewCaptain
KiroCrewCaptain merged commit fd0558f into main Nov 17, 2026
103 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/relay-host-gone-offline-state branch November 17, 2026 06:53
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Relay Crew window and local dashboard: a stopped host shows red per-panel errors instead of one calm offline state

2 participants