Repository navigation
feat(dashboard): warn on stale SPA bundle via build-id freshness check - #18756
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check that [DESIGN-REVIEWED] 7b9185a Description read[DESCRIPTION-READ] 973d762401bec70a594f77609dbda9d5bae6fad5c13ac26d4e81da57dc9fac09 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 Nothing to check. [UX-REVIEWED] 7b9185a Description read[DESCRIPTION-READ] f9c3e757eaec61c231b7d32b4a088a8d5af9afb9c33853afcafb6425b5986afc That sha256 names everything this verdict read: the PR description, plus the 3 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 |
First Principles Review (Opus 5.5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The vite stamp creates a second file for the identity Not justified as shipped
What this change shipsInventory (4 items) — 2 justifiedIntent: an operator wants to be told when the dashboard is serving a frontend bundle older than the source the backend is running. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 7b9185a Description read[DESCRIPTION-READ] 4c563855550a3f3f6eba14462e125c8e20dae9fdbf4843ec88222f95319d3286 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
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: |
00d2236 to
c201226
Compare
c201226 to
e4534ea
Compare
893a6ef to
e2c4105
Compare
e2c4105 to
798a63e
Compare
|
Converted to draft by crew-pr-reviewer: the self-review above is CHANGES NEEDED. Mark ready again (gh pr ready 18756) once the points are addressed. |
798a63e to
c854056
Compare
|
Addressed the CHANGES NEEDED self-review above (and the Design / First Principles CONCERNS) on head c854056, rebased onto current main (conflict in
Uncommitted |
c854056 to
3066c1d
Compare
3066c1d to
8d2893b
Compare
8d2893b to
33fd568
Compare
|
Review follow-up on 8d2893b → 33fd568:
|
… check Re-ported onto current main (replaces #4913). The guard compares the git tree id of website/ (HEAD:website), not whole-repo HEAD, so a backend-only or docs-only commit after a build no longer reports a correct bundle as stale. The dist side reads the websiteTree that buildIdPlugin stamps into dist/build-id.json on every vite build (only when website/ is clean), falling back to main's kirocrew-build-source.txt fingerprint for a dist with no build-id.json; packaged installs bake WEBSITE_TREE in scripts/stamp-distribution.sh. The source-checkout probe reuses code_fingerprint's trusted git path (trusted_git_bin + hardened_git_env). The unread builtAt field is dropped. Co-authored-by: Jeff Strunk <strunkjd@amazon.com>
33fd568 to
7b9185a
Compare
buluoray
left a comment
There was a problem hiding this comment.
Approving 7b9185a.
This adds a one-time, warn-only startup check: if the served dashboard bundle was built from a different website/ tree than the running backend, the gateway logs a WARNING. It adds no endpoint, no polling and no browser-side surface.
What I checked:
- Bounded:
gateway.pyawaitscheck_bundle_freshnessonce on the subprocess executor. The only process it can start isgit rev-parse HEAD:website, capped at a 5s timeout. Nothing repeats. - No false positives on fresh installs, dev builds or backend-only commits:
- It warns only on a confident mismatch between two known tree ids (
stale_bundle_guard.py:136-155). A missing stamp, a dirty or git-less build, an unknown backend tree and malformed JSON all skip without warning, and any exception is caught and logged at debug level (:159-162). - Both the Vite plugin and
frontend._write_build_source_fingerprintstamp only whenwebsite/is clean, and the plugin isapply: 'build', so the dev server never runs it. - Using the
HEAD:websitetree id rather thanHEADkeeps a backend-only commit after a build silent, which the real-git test covers. - A fresh
build-id.jsoncorrectly outranks a leftoverkirocrew-build-source.txt, and a dirty build doesn't fall back to it.
- It warns only on a confident mismatch between two known tree ids (
- Trusted git path: the source-checkout fallback goes through
trusted_git_bin()+hardened_git_env()and spawns nothing when no trusted git exists. The newBENIGN_SPAWNSentry is accurate. - Nothing exposed:
build-id.jsonis not served. The PWA root-file route only matches manifest/sw/icons/worklet, and no auth path changes. - Packaged and desktop builds:
stamp-distribution.shbakesWEBSITE_TREEfrom the build checkout, which encloses the Electronbackend-dist/staging tree, so it matches the bundle copied in. If git is unavailable it bakes "" and the check skips. ImportingWEBSITE_TREEseparately keeps older_build_info.pyfiles from unbindingDISTRIBUTION. - Stamp survives the build's atomic publish: writing into the resolved
config.build.outDirmeans the stamp ridesatomicPublishPlugin's scratch-and-publish, the same patternswVersionPluginuses.
Each key guard is pinned by a named test. Reverting the dirty-build no-fallback, the unknown-backend skip, the baked-value preference, the trusted-git requirement or the catch-all each turns its corresponding test red. I didn't find a test for the Vite plugin, so I checked it from source only.
Non-blocking follow-ups:
- The rebuild guidance in the warning (
cd website && npm run build, copy intostatic/dist) only applies to a source checkout. If a packaged build ever ships with a mismatched bundle, consider wording that fits how the app was installed. - A small frontend test for
buildIdPlugin's clean/dirtywebsiteTreestamping would protect the contract the backend relies on.
bolichen97
left a comment
There was a problem hiding this comment.
Approved at head 7b9185a: PR Readiness is green, no open change requests, and the review lanes passed. (AI-assisted review at bolichen97's request.)
Fixes #3395
Replaces #4913 (by @jstrunk — re-ported here because that fork PR needed a maintainer push to drive green).
Re-port of @jstrunk's
feat/dist-staleness-guardonto currentmain. The original author's commit and authorship are preserved (Co-authored-by).Problem / Motivation
Goal: Give the operator a startup signal when the dashboard is serving an SPA bundle that was built from different frontend source than the running backend.
The gateway serves the dashboard SPA from a gitignored, build-copied
src/kiro_crew/static/dist/. Nothing verifies that the served bundle was built from the samewebsite/source as the running backend, so a restart that did not rebuild/restage the frontend keeps serving an OLD bundle silently. The UI renders (assets are present), so the gap only surfaces when a behavioral test fails against a stale UI. Full write-up in #3395.Why it matters
Silent staleness is the worst-case shape: no error, no missing asset, no crash — the UI just quietly serves outdated behavior, and the operator has no signal that a rebuild/restage was skipped. The existing vanish-watchdog cannot catch it (the dist is present, just old).
Not a goal
stale_asset_watchdog.py, which is a presence check with a CRITICAL + graceful-shutdown response, correct for a vanished dist. This is a different failure mode with a deliberately different (warn-only) response.HEAD:websitetree id thatfrontend._write_build_source_fingerprintalready records inkirocrew-build-source.txt(read by Dev Fleet's rebuild skip).What changed
Identity is the git tree id of
website/(git rev-parse HEAD:website), not whole-repoHEAD. It changes iff a tracked frontend file changes, so a backend-only or docs-only commit after a build does not make a correct bundle look stale.src/kiro_crew/dashboard/stale_bundle_guard.py(new) —check_bundle_freshness()compares the dist'swebsite/tree against the backend's. Dist side:websiteTreeindist/build-id.json(rewritten by everyvite build), falling back to main'skirocrew-build-source.txtonly when there is nobuild-id.json, so a leftover fingerprint can never outrank a fresher build. Backend side: baked_build_info.WEBSITE_TREE(packaged install), elsegit rev-parse HEAD:websitethrough the same trusted git path ascode_fingerprint(trusted_git_bin+hardened_git_env). A confident mismatch → oneWARNINGwith rebuild guidance. Every "cannot verify" case (no stamp, dirty/git-less build, unknown backend tree, malformed JSON) skips silently. Never raises, never shuts down. Run off the event loop viarun_in_executor(subprocess_executor(), ...).website/vite.config.ts— newbuildIdPluginwritesdist/build-id.json{ buildId, websiteTree }atvite buildtime (covers a hand-runnpm run build, which replaces the dist without akirocrew-build-source.txt). Like main's fingerprint,websiteTreeis stamped only whenwebsite/is clean, since a dirty build compiled contentHEAD:websitedoes not describe.scripts/stamp-distribution.sh+beacon.baked_website_tree()— bakeWEBSITE_TREE(HEAD:website) into the generated_build_info.py(empty-safe; imported separately so an older stamp cannot unbindDISTRIBUTION).src/kiro_crew/slack/gateway.py— one call at startup, next to the vanish-watchdog wiring (kept beside main's new sign-in refresher task).Backwards compatibility
Removes nothing: adds a startup log path, one dist stamp file and one baked field.
beacon.baked_website_tree()andWEBSITE_TREEare new and imported defensively.Tests
pytest test/test_stale_bundle_guard.py— tree mismatch warns; match / no stamp / unknown backend tree / empty dist tree / malformed JSON skip silently; a freshbuild-id.jsonwins over an oldkirocrew-build-source.txt, and a dirty build does not fall back to it; never raises. Real-git tests: a backend-only commit after a build stays silent, awebsite/commit after a build warns._backend_website_treeprefers the baked value, usestrusted_git_bin+hardened_git_env, and skips with no spawn when git is untrusted.test/test_spawn_audit.py—_backend_website_treeregistered inBENIGN_SPAWNS.isort/flake8/mypy/ baselinedblack/ subprocess-encoding gate clean on changed files.Manual verification
N/A — the only user-visible surface is a single backend log line, asserted by the unit tests and the real-git tests; there is no UI change to click through.
Screenshots / video
Why no screenshot: this change adds a backend startup log line and build-identity stamps; it renders no dashboard pixels.
Related Issues
Fixes #3395. Replaces #4913.
Checklist