Repository navigation
Conversation
added 2 commits
November 21, 2026 04:40
The admission guard refuses every job while `clock.state` is `fail`, and `/readyz` answers 503, but nothing under `src/views/` read the clock: a user learned the platform could not start work only after pressing Run now and reading the refusal. The dashboard route now passes the same `clockState()` the guard and `/readyz` read into `dashboardPage`, which emits one critical `AlertView` when the state is `fail` and names the measured `skewSeconds` and `thresholdSeconds` in both locales, with the host-clock recovery step. It renders as a banner above the collapsed secondary section rather than as a row in the alert table, because that table lives inside the collapsed section and a refused job is not a detail a user should have to expand. Only `fail` paints it: `ok`, `unknown` and `not-configured` render nothing, so a GitHub outage or an app-less deployment does not produce a permanent red banner. `/readyz` and the `CLOCK_SKEW` refusal sentence are unchanged. Docs-not-needed: docs/architecture.md carries the dashboard rule in this commit.
…banner The banner interpolation sat on its own template line, so an absent clock left an indented empty line in the rendered HTML and the mock dashboard fixture drifted. The banner now brings its own leading newline and an absent reading emits nothing, so the no-banner render is byte-identical to the base and `mock/` needs no regeneration.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Written-by: Fledge Platform Dev-4
Fixes #1198
The defect
The admission guard refuses every job while
clock.stateisfail, and/readyzanswers503, but nothing undersrc/views/read the clock —grep -i clock src/views/ public/found no surface at all. On the live host the state isfailwithskewSeconds: 1688againstthresholdSeconds: 120, so manual, scheduled and follow-up triggers are all refused and the dashboard says nothing. A user learned it only after pressing Run now and reading the refusal;docs/deploy.md:1615-1618already promises "the console banner names the measured seconds".What changed
src/app.ts/dashboardpassesclock: githubApp.clockState()— the same object the guard reads atsrc/jobs/service.ts:1291and/readyzreads atsrc/app.ts:1218.src/views/pages.tsadds an optionalclockinput andclockFailAlert(), which emits oneAlertViewwithlevel: 'critical'and a newkind: 'clock_skew'only whenstate === 'fail'.alertTextrenders it through the existing bilingualt(): the measured seconds, the threshold, and the host-clock recovery (timedatectl set-ntp true, then/readyzreturns 200 within one measurement window).src/db.tsgivesAlertViewoptionalskewSeconds/thresholdSeconds.messageis one string and cannot carry the zh/en pair, andStore.alertsnever sets either field.docs/architecture.mdrecords the display rule beside the clock section./readyz, theCLOCK_SKEWrefusal atsrc/lib/failure.ts:282, the threshold and the refusal contract are untouched.Why a banner and not a row in the existing alert table
The dashboard's "Needs attention" table is rendered inside
<details class="secondary">("More: repositories, delivery and jobs"), which is collapsed unless a deep link or a paged list opens it. A critical alert placed there would satisfy a text search and show the user nothing without expanding "More" — exactly the failure this card is about. The banner renders above that section, directly under the masthead, withrole="alert".Absence half
Only
failpaints it.okrenders nothing,unknownrenders nothing (a young process, or a GitHub outage past the 15-minute reuse window), andnot-configuredrenders nothing (a deployment with no App is not a clock verdict).test/clockFailBanner.test.tsasserts all three across both locales, and asserts an absent reading renders byte-identical to a healthy one.Ran:
npm run check— pass (lint 11 baseline warnings in 8 entries, typecheck, 3268/3268 tests, build)node scripts/version.mjs check— pass (version: 0.4.4 ok)npx tsx --test test/clockFailBanner.test.tsat the basef1c48ed3— red:zh: expected exactly one clock banner, rendering it 0 timesGET /readyz→503,clock.state: "fail",skewSeconds: 1688,thresholdSeconds: 120; the banner is present at both widths in both locales anddocument.scrollWidthnever exceeds the viewportNot run: Docker image, real SMTP, a production deploy (owner action, out of this slice).
Frames
Shot from a Fledge instance booted from this branch. The before run has no GitHub App (
clock.state: not-configured), so it shows the dashboard with no clock surface; the after run pointsGITHUB_API_BASEat a local fake whoseDateheader is 1688 s behind, which is the offset production reported. Same data directory, login and mock runner in both.Before — en 1280:

After — en 1280:

Before — zh 1280:

After — zh 1280:

Before — en 360:

After — en 360:

Before — zh 360:

After — zh 360:

Evidence branch
evidence/1198-clock-fail-bannercarries the frames and a README stating how they were produced. Measured on the after run: 1116x69 at 1280 (x=82, y=414), 328x178 at 360 (x=16, y=545), no horizontal overflow.Uncertainty and residual risk
/settings,/adminand the repository page do not carry it; the card scoped one view change, so a user who lands elsewhere first still meets the refusal sentence rather than the banner. Widening it is a separate card.skewSecondsreads as a clock behind rather than ahead; the number keeps its sign instead of being absolute, because the direction is what tells an operator which way to correct./readyzremains the monitor's signal.AlertViewgained two optional fields; every existing constructor keeps compiling andStore.alertsnever sets them.Alternatives considered
AlertView.message(rejected: one string, no zh/en pair, and the existingalertTextswitch is how every other kind stays bilingual).alerts(rejected: the view owns alert wording, and the route has no translator).