Skip to content

feat(dashboard): warn on stale SPA bundle via build-id freshness check - #18756

Merged
bolichen97 merged 1 commit into
mainfrom
replace/4913-stale-bundle-guard
Oct 12, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
replace/4913-stale-bundle-guard

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

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-guard onto current main. 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 same website/ 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

  • No change to 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.
  • No new build-identity scheme: this reuses the HEAD:website tree id that frontend._write_build_source_fingerprint already records in kirocrew-build-source.txt (read by Dev Fleet's rebuild skip).
  • No shutdown or hard-fail on staleness — a restart alone re-serves the same dist, so a shutdown response would just loop.

What changed

Identity is the git tree id of website/ (git rev-parse HEAD:website), not whole-repo HEAD. 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's website/ tree against the backend's. Dist side: websiteTree in dist/build-id.json (rewritten by every vite build), falling back to main's kirocrew-build-source.txt only when there is no build-id.json, so a leftover fingerprint can never outrank a fresher build. Backend side: baked _build_info.WEBSITE_TREE (packaged install), else git rev-parse HEAD:website through the same trusted git path as code_fingerprint (trusted_git_bin + hardened_git_env). A confident mismatch → one WARNING with 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 via run_in_executor(subprocess_executor(), ...).
  • website/vite.config.ts — new buildIdPlugin writes dist/build-id.json { buildId, websiteTree } at vite build time (covers a hand-run npm run build, which replaces the dist without a kirocrew-build-source.txt). Like main's fingerprint, websiteTree is stamped only when website/ is clean, since a dirty build compiled content HEAD:website does not describe.
  • scripts/stamp-distribution.sh + beacon.baked_website_tree() — bake WEBSITE_TREE (HEAD:website) into the generated _build_info.py (empty-safe; imported separately so an older stamp cannot unbind DISTRIBUTION).
  • 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() and WEBSITE_TREE are 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 fresh build-id.json wins over an old kirocrew-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, a website/ commit after a build warns. _backend_website_tree prefers the baked value, uses trusted_git_bin + hardened_git_env, and skips with no spawn when git is untrusted.
  • test/test_spawn_audit.py — _backend_website_tree registered in BENIGN_SPAWNS.
  • isort / flake8 / mypy / baselined black / 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

  • One commit, 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

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 10, 2026 07:02
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 10, 2026
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 7b9185ae5dc905efe02c035418dc9672bc1128ec — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that stamp-distribution.sh's git -C "$PKG_DIR" finds a repo when packaging/build-desktop.sh runs it on a staged "$sp/kiro_crew". If that path sits outside the checkout, WEBSITE_TREE is baked empty and the guard does nothing on desktop installs, without telling anyone.

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 7b9185ae5dc905efe02c035418dc9672bc1128ec — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 .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 Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 7b9185ae5dc905efe02c035418dc9672bc1128ec — 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The vite stamp creates a second file for the identity kirocrew-build-source.txt already holds, and the baked WEBSITE_TREE guards packaged installs that cannot go stale.

Not justified as shipped

  • Item 2 — duplicate of src/kiro_crew/frontend.py::_write_build_source_fingerprint: build-id.json's websiteTree holds the same "HEAD:website, clean only" identity. Two writers and two filenames need _read_dist_tree's precedence rule, while the description says "No new build-identity scheme".
    Subtraction: have buildIdPlugin write the tree id into dist/kirocrew-build-source.txt, then delete build-id.json, _BUILD_ID_PATH, buildId (its only consumer is the log string) and the precedence branch.
    Clears when: one stamp file is left, or a case is named where one file cannot serve both readers.
  • Item 3 — inherited: build-wheel.yml runs stamp (l.83), build (l.89) and copy (l.95) from one checkout in one job. build-desktop.sh stamps a staged $sp/kiro_crew, where git -C gives "". So the baked tree never differs from the shipped dist.
    Subtraction: delete the WEBSITE_TREE line in stamp-distribution.sh, beacon._BAKED_WEBSITE_TREE/baked_website_tree() and the baked branch in _backend_website_tree.
    Clears when: a packaged artifact is shown serving a dist built from a different website/ tree.

What this change ships

Inventory (4 items) — 2 justified

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

  1. At gateway startup, a one-time WARNING with rebuild steps when the dist's website/ tree differs from the backend's — justified
  2. vite build writes a new dist/build-id.json stamp — duplicate of frontend._write_build_source_fingerprint
  3. Packaged builds bake WEBSITE_TREE into _build_info.py, plus a new beacon.baked_website_tree() — inherited, no packaged staleness path
  4. A new git spawn is allowlisted in BENIGN_SPAWNS — justified

[FIRST-PRINCIPLES-REVIEWED] 7b9185a

Description read

[DESCRIPTION-READ] 4c563855550a3f3f6eba14462e125c8e20dae9fdbf4843ec88222f95319d3286

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 Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7b9185a

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 7b9185ae5dc905efe02c035418dc9672bc1128ec: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 7b9185a

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 7b9185ae5dc905efe02c035418dc9672bc1128ec: <one-sentence reason>

@iamwhatever
iamwhatever force-pushed the replace/4913-stale-bundle-guard branch 3 times, most recently from 00d2236 to c201226 Compare October 10, 2026 07:50
@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 Oct 10, 2026
@iamwhatever
iamwhatever force-pushed the replace/4913-stale-bundle-guard branch from c201226 to e4534ea Compare October 10, 2026 18:45
@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 Oct 10, 2026
@iamwhatever
iamwhatever force-pushed the replace/4913-stale-bundle-guard branch 2 times, most recently from 893a6ef to e2c4105 Compare October 10, 2026 20:43
@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 Oct 10, 2026
@iamwhatever
iamwhatever force-pushed the replace/4913-stale-bundle-guard branch from e2c4105 to 798a63e Compare October 10, 2026 22:02
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 10, 2026
@iamwhatever
iamwhatever marked this pull request as draft October 11, 2026 00:23
@iamwhatever

Copy link
Copy Markdown
Contributor Author

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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 11, 2026
@iamwhatever
iamwhatever force-pushed the replace/4913-stale-bundle-guard branch from 798a63e to c854056 Compare October 11, 2026 08:02
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Addressed the CHANGES NEEDED self-review above (and the Design / First Principles CONCERNS) on head c854056, rebased onto current main (conflict in slack/gateway.py resolved by keeping main's sign-in refresher task and the freshness check side by side):

  1. Wrong identity (whole-repo HEAD) — the guard now compares the website/ git tree id (HEAD:website) on both sides. A backend-only or docs-only commit no longer makes a correct bundle look stale.
  2. Reuse main's fingerprint — the dist side reads kirocrew-build-source.txt (frontend._write_build_source_fingerprint) first, falling back to websiteTree in build-id.json for a hand-run npm run build. buildIdPlugin stamps websiteTree only when website/ is clean, same rule as main's writer, so a dirty build is never stamped as HEAD:website.
  3. stamp-distribution.sh — bakes WEBSITE_TREE (HEAD:website) instead of COMMIT; beacon.baked_commit() became beacon.baked_website_tree().
  4. Second git probe — _backend_website_tree now uses code_fingerprint's trusted path: trusted_git_bin() + hardened_git_env() + core.pager=cat.
  5. builtAt — removed (commit too; buildId stays for the log line).
  6. Test — test_backend_only_commit_after_build_stays_silent (real git repo) plus test_frontend_commit_after_build_warns.

Uncommitted website/ edits that were never rebuilt still compare as the committed tree; a build of such a tree now writes no stamp, so the guard skips rather than claiming fresh. PR body updated to match.

@iamwhatever
iamwhatever force-pushed the replace/4913-stale-bundle-guard branch from c854056 to 3066c1d Compare October 11, 2026 08:24
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 11, 2026
@iamwhatever
iamwhatever force-pushed the replace/4913-stale-bundle-guard branch from 3066c1d to 8d2893b Compare October 11, 2026 08:51
@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 Oct 11, 2026
@iamwhatever
iamwhatever force-pushed the replace/4913-stale-bundle-guard branch from 8d2893b to 33fd568 Compare October 11, 2026 09:31
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Review follow-up on 8d2893b → 33fd568:

  • Design CONCERN (old fingerprint outranks fresh build-id.json) — fixed. build-id.json now wins whenever it parses; kirocrew-build-source.txt is read only when there is no build-id.json. A dirty build (empty websiteTree) skips instead of falling back. Tests: test_fresh_build_id_wins_over_old_fingerprint, test_dirty_build_id_does_not_fall_back_to_old_fingerprint.
  • Design suggestion (fire-and-forget) — not taken here: the check runs on the subprocess executor, git is bounded at 5s, and a single await keeps startup ordering simple. Happy to change if a maintainer prefers.
  • First Principles CONCERN (baked WEBSITE_TREE for packaged installs) — kept on purpose. The CHANGES NEEDED self-review asked for exactly this (“bake that tree id, not HEAD, in scripts/stamp-distribution.sh”). It is a few empty-safe lines, and it lets the guard catch a package whose staged dist came from a different website/ tree than its backend. Leaving it for the maintainer to cut if unwanted.

@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 Oct 11, 2026
… 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>
@iamwhatever
iamwhatever force-pushed the replace/4913-stale-bundle-guard branch from 33fd568 to 7b9185a Compare October 11, 2026 19:12
@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 Oct 11, 2026
@iamwhatever
iamwhatever marked this pull request as ready for review October 11, 2026 20:00
@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 Oct 11, 2026

@buluoray buluoray 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.

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.py awaits check_bundle_freshness once on the subprocess executor. The only process it can start is git 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_fingerprint stamp only when website/ is clean, and the plugin is apply: 'build', so the dev server never runs it.
    • Using the HEAD:website tree id rather than HEAD keeps a backend-only commit after a build silent, which the real-git test covers.
    • A fresh build-id.json correctly outranks a leftover kirocrew-build-source.txt, and a dirty build doesn't fall back to it.
  • Trusted git path: the source-checkout fallback goes through trusted_git_bin() + hardened_git_env() and spawns nothing when no trusted git exists. The new BENIGN_SPAWNS entry is accurate.
  • Nothing exposed: build-id.json is not served. The PWA root-file route only matches manifest/sw/icons/worklet, and no auth path changes.
  • Packaged and desktop builds: stamp-distribution.sh bakes WEBSITE_TREE from the build checkout, which encloses the Electron backend-dist/ staging tree, so it matches the bundle copied in. If git is unavailable it bakes "" and the check skips. Importing WEBSITE_TREE separately keeps older _build_info.py files from unbinding DISTRIBUTION.
  • Stamp survives the build's atomic publish: writing into the resolved config.build.outDir means the stamp rides atomicPublishPlugin's scratch-and-publish, the same pattern swVersionPlugin uses.

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 into static/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/dirty websiteTree stamping would protect the contract the backend relies on.

@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.

Approved at head 7b9185a: PR Readiness is green, no open change requests, and the review lanes passed. (AI-assisted review at bolichen97's request.)

@bolichen97
bolichen97 merged commit 56f737e into main Oct 12, 2026
106 checks passed
@bolichen97
bolichen97 deleted the replace/4913-stale-bundle-guard branch October 12, 2026 05:05
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 12, 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.

Dashboard serves a stale SPA bundle silently — add a build-id freshness guard

4 participants