Skip to content

fix(dashboard): keep feature-preview switches on the gateway - #21602

Closed
mbriones98 wants to merge 2 commits into
mainfrom
fix/preview-flags-persist-21396-v2
Closed

mbriones98 wants to merge 2 commits into
mainfrom
fix/preview-flags-persist-21396-v2

Conversation

@mbriones98

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Feature previews switch (such as Crewmates) stays on once you turn it on, in every browser and in the desktop app that use the same Kiro Crew.

The switches under Settings > Developer > Feature previews were kept only in browser localStorage (mc-preview-*). A new origin or port, the desktop app next to a browser tab, or cleared site data each read the switch as off, so Crewmates and the other previews kept turning themselves off.

Why it matters

Anyone trying a preview has to turn it on again on every surface and after every storage reset. A preview that seems to switch itself off reads as broken.

Not a goal

  • No change to what any preview does once it is on.
  • No new route and no auth change: writes go through the existing owner-only config PATCH.
  • No per-user scope. The switches belong to the gateway, like every other dashboard setting in config.
  • No change to the DURABLE_PREF_KEYS / /api/ui-prefs backup, so there is one source of truth.
  • No configKey / settings-registry entries for the new paths (<SettingRef> deep links). That is a separate navigation feature.

What changed (motivation → approach → change)

Symptom: a switch turned on in one surface is off in another. Root cause: localStorage was the only copy.

#21396 was filed by its owner asking for the switches to sync across surfaces, so moving them from per-device to gateway-wide is the requested behaviour, not a side effect.

Approach: the gateway config keeps each switch, and localStorage stays as a fast cache. Config rather than adding the keys to DURABLE_PREF_KEYS: the uiPrefs backup restores only on a cold profile, so a warm desktop app and a warm browser tab would never pick up each other's change. The config route reaches every open dashboard through the config refresh frame it already receives.

  • Backend (sections_dashboard.py, loader_builders.py, loader.py, sections.py, handlers/core.py, change_card_catalog.py):
    • One bool per switch under dashboard.feature_previews.<name>, for the 6 live flags: webhooks, artifact_deploy, crew, remote_crew_chat, layout_harness, folder_conductor.
    • The PATCH allowlist accepts only those names, typed bool. The loader drops unknown names and non-bool values.
    • The change card classifies the new paths, and configuration.md and config-baseline.json are updated.
    • The retired mc-preview-instance-sessions key is not kept on the gateway. Its ON is carried up as remote_crew_chat.
  • Dashboard (usePreviewFlagServerSync.ts, mounted in App.tsx beside the shell's existing reader of the same config query, so boot order is unchanged):
    • Reconcile: the server value wins over the cache, except for a flag whose write is still in flight.
    • Write order: each toggle is PATCHed, and writes for one flag are sent one after another so the last click is what the gateway keeps.
    • One-time carry-up: a switch set only in this browser before the gateway kept the switches is carried up once with if_unset, so it never replaces a stored value.
    • Sync marker: afterwards a kc-feature-previews-synced marker makes a cache-only ON read as off, so a key the operator removed stays off. The marker is not set while a toggle is in flight, or after a refused toggle or a refused carry, so a browser-only value is never wiped.
    • Refused toggle: the switch goes back to the last value the gateway accepted, and the section shows an error notice naming the switch. On a 403 it says only the owner can change feature previews. On any other failure, including a 403 from an expired session, it says the save failed.
    • Refused carry: the notice says the switch is on in this browser only.
  • Copy:
    • The section description no longer says "per-device". It now says the switches are saved for everyone using this Kiro Crew ({{productName}}), without the word "gateway".
    • Three new notice strings.
    • All 12 translated catalogs are updated, and en-XA is regenerated.

Overlap: open PR #20420 also edits DURABLE_PREF_KEYS. This PR does not touch that list, so the two do not conflict.

Backwards compatibility

Compatible: the new config fields are optional and default to off, the PATCH allowlist only gains names, and an existing browser-only ON is carried up once instead of being dropped.

The diff takes one thing away: localStorage is no longer the source of truth for a switch. Once synced, a cache-only ON that the gateway does not hold reads as off, and a non-owner's toggle no longer overrides the gateway's stored value.
Reader: website/src/utils/previewFlags.ts:readPreviewFlag -- chat|crew page -- still reads the cache, which reconcile keeps equal to the gateway copy | previewFlagServerSync.test.tsx "lets the server copy win over a stale browser copy"
Reader: website/src/hooks/usePreviewFlag.ts:usePreviewFlag / useRemoteCrewChat -- chat|crew page -- re-renders on the same cache write event | previewFlagServerSync.test.tsx "turns Crewmates on from the server when this browser has no copy"
Reader: website/src/surfaces/registry.ts:surfacePreviewEnabled (nav rail, pagesProvider, appNavHidden, CommandBarOverlay) -- chat|crew page -- reads the cache via readPreviewFlag | previewSurfaces.test.tsx
Reader: website/src/pages/settings/FeaturePreviewsSection.tsx -- crew page -- toggles still write the cache first, then the gateway | previewSurfaces.test.tsx "says why a switch went back when the gateway refuses the write"
Reader: retired mc-preview-instance-sessions -- chat -- carried up as remote_crew_chat, then cleared | previewFlagServerSync.test.tsx "carries the retired Remote crew sessions switch up as Chat on a crew", "never lets the retired key turn Chat on a crew back on after it was turned off"

Tests

  • website/src/test/previewFlagServerSync.test.tsx (30 tests). The repro: Crewmates turns on from the server when localStorage is empty, and it fails with the sync disabled. The other tests cover:
    • writes, in-flight protection, and rapid toggles applied in click order;
    • a refused toggle reverting in synced and unsynced browsers, with no config body, after two or three refused clicks, and behind a refused carry;
    • the notice waiting for the last queued click, and being cleared only by a save of the same switch;
    • a 403 from an expired session reported as a failed save;
    • the one-time if_unset carry-up, not replacing a stored value, a 409 counted as synced, and a refused carry reported and kept on;
    • the sync marker not being set while a toggle is in flight, whether the in-flight read lands from the config read or from another switch's carry;
    • the retired key;
    • parity between PREVIEW_FLAGS and every declared flag constant.
  • I removed each of these lines on a scratch copy, and each removal makes a test fail:
    • the revert itself;
    • the per-flag baseline;
    • the in-flight guards;
    • the pending.size guard;
    • the last-queued-click guard on the notice;
    • the same-switch notice clear.
  • website/src/test/previewSurfaces.test.tsx: the section shows the owner-only notice naming the switch when the PATCH returns 403.
  • test/test_feature_previews_config.py (25 tests):
    • the gateway list matches the dashboard flags, and nothing is on by default;
    • the loader keeps only known names with bool values;
    • each switch is writable, and unknown names or non-bools write nothing;
    • if_unset writes an absent switch and never replaces a stored one;
    • a non-owner cannot write a switch.
  • Local runs on this commit:
    • Frontend: full vitest suite, 3,071 of 3,072 files pass. The one failure, MarkdownRenderer.domGolden.test.tsx, fails the same way on origin/main on this host. tsc (app), eslint src/ --max-warnings 0 and jscpd are clean. i18n-check.mjs and check-i18n-strings.mjs pass with I18N_BASE_REF set to the base commit.
    • Backend: full pytest run. Its failures match a run of the same 57 files on origin/main on this host, except 4 signal and process-timing tests that pass when re-run alone. The shared failures come from the host: an enterprise profile, a live KIROCREW_HOME, and no userns. black, isort, flake8 and mypy are clean on the changed Python.
  • Local AI review: GPT (gpt-6.1-sol) and Opus read-only reviews ran over several rounds. Each quoted the commit SHA it read, and I checked those against the worktree. Every Critical/High/Medium finding is fixed in this commit, and the final round on the last code change found none open.

Manual verification

I took screenshots against the built SPA, with /api/config/kirocrew returning crew: true:

  • With empty localStorage, Crewmates shows on.
  • With the PATCH returning 403, flipping Webhooks puts it back and the notice names it.
  • With a browser-only Webhooks ON and the carry PATCH returning 500, the notice says it is on in this browser only.

Screenshots / video

Synced from the gateway (Crewmates on, empty browser storage):

Feature previews section synced from the gateway

A toggle refused with 403, naming the switch:

Owner-only notice naming Webhooks

A browser-only switch whose carry-up failed:

On in this browser only notice

Related Issues

Fixes #21396

Related: #16237, #17424, #14232, #9876

Supersedes #21569.

Pattern harvest

Rule candidate: review-prompt
Pattern: a user-visible setting persisted only in browser localStorage, when it is meant to hold across surfaces of the same gateway; check whether it should live in gateway config with localStorage as a cache.

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

The Feature previews switches lived only in browser localStorage, so a
new origin, the desktop app beside a browser tab, or cleared site data
turned them back off. Each switch is now stored in the gateway config
under dashboard.feature_previews.<name>, written through the existing
owner-only config PATCH, with localStorage kept as a cache. A switch set
only in this browser is carried up once with if_unset; a refused toggle
names the switch that went back and says why.

Fixes #21396
@mbriones98
mbriones98 requested review from a team and KiroCrewCaptain as code owners October 17, 2026 11:38
@mbriones98
mbriones98 enabled auto-merge (squash) October 17, 2026 11:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 17, 2026
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that a non-owner dashboard session, whose toggles now revert, is an accepted loss: previews it could switch on locally before are now owner-only.

[DESIGN-REVIEWED] 051d058

Description read

[DESCRIPTION-READ] d9c561213f4f9a0a5a1d7c281c6212bd6b4b629d6df1a774caca1b270f283b8b

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 051d05897380c7a2a37acfe49c79ea71daa6e287 — 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 one-time carry-up migration (sync marker, carry counters, carry-failed notice in 13 catalogs) costs more than re-ticking an unreleased preview once.

Not justified as shipped

  • Item 4 — oversized: the Goal is that "a … switch stays on once you turn it on". The carry-up only matters during the upgrade, and only for switches on unreleased previews. Even so it brings in carried, carriesInFlight, carryFailed, PREVIEW_FLAGS_SYNCED_KEY/markSynced, the carry?: true error variant, the if_unset carry path, and feature_previews_carry_failed in 13 locale files. If the PR ships without it, a preview tester turns each switch on once more after upgrading.
    Subtraction: delete the carry-up branch and the sync marker in reconcilePreviewFlags, so the gateway value wins and an absent name reads as off. Drop the carry variant and its string in all 13 catalogs.
    Clears when: the carry-up is removed, or the PR names a user for whom re-ticking once after the upgrade is a real loss.
  • Item 8 — undeclared: the eager-spawn shutdown change in chat_runner.py/exit_path.py is the same change as base commit 8b709b4 (fix(dashboard): stop speculative session starts when the gateway shuts down #21552). The description never mentions it.
  • Item 9 — undeclared: the WakaTime headline and summary now use the include-other totals. This changes what users see and the description never mentions it.
  • Item 10 — undeclared: the timeouts in test_session_pool.py go from 2 s to 30 s.

What this change ships

Inventory (10 items) — 5 justified

Intent: keep a Feature previews switch set across every browser and the desktop app using one gateway. FIX.

  1. Preview switches are saved in gateway config and shared by every surface — justified
  2. dashboard.feature_previews.<name> gets six bools that the owner-only PATCH can write — justified
  3. A non-owner's toggle is refused, put back, and a notice says why — justified
  4. A switch on only in this browser is carried up once, behind a sync marker and a "this browser only" notice — oversized
  5. The retired Remote crew sessions switch is carried up as Chat on a crew — rides along, goes with item 4
  6. The section text no longer says "per-device" (12 catalogs) — justified
  7. Rapid toggles of one switch save in click order; a read during a save doesn't flip it back — justified
  8. Gateway shutdown cancels pending speculative session starts — undeclared, matches base fix(dashboard): stop speculative session starts when the gateway shuts down #21552
  9. WakaTime totals include the "Other" bucket — undeclared
  10. Session-pool test timeouts raised to 30 s — undeclared

[FIRST-PRINCIPLES-REVIEWED] 051d058

Description read

[DESCRIPTION-READ] 3957afde2f99bc997672473b08afbd350762e80f69c67ad4ed9931b5b9c3f5fd

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

The new "saved for everyone using this Kiro Crew" copy reads as "other people", so the blind reader got nervous about touching switches in a single-user tool.

Watch

  • Intro copy implies other people. The string feature_previews_desc says "saved for everyone using this {{productName}}". The blind reader took this to mean "whatever I change here affects other people too". They said it "make[s] me nervous about touching anything" and that they would not turn Crewmates off because "other people may depend on it". The PR's goal is "every browser and the desktop app", not other users. This line sits on every visit to the section and makes people hesitate to use the switches. Medium severity.
  • Carry-failed notice (shot-03) is red while the switch shows on. The reader said "I'm confused that the switch looks fully on even though it says saving failed. If I reload, I don't know whether I'll lose it." It uses the same red bar as the denied notice, so the reader also "can't tell how serious each one is". It shows at most once per browser, but it leaves the user unsure what state the switch is in. Low–medium severity.
  • "Only the owner of this Kiro Crew" (shot-02). The reader said "I don't know who that is, or whether it's me." The notice explains why the switch went back but not who to ask. Low severity.

Suggestions

  • feature_previews_desc: change to "These switches are saved on this {{productName}}, so they stay set in every browser and in the desktop app." The same "for everyone using" wording also appears in feature_previews_carry_failed.
  • feature_previews_carry_failed: make it say the switch is safe, e.g. "“{{name}}” is on here, but not saved yet. Reload the page to save it; it stays on in this browser."
  • Attach a screenshot of the feature_previews_save_failed variant. No supplied screenshot shows it.

[UX-REVIEWED] 051d058

Description read

[DESCRIPTION-READ] ebe5eae54913475646c2de3d4d8d5188501c69d5a6722eb748a5ddd552f43178

That sha256 names everything this verdict read: the PR description, plus the 6 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 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 051d05897380c7a2a37acfe49c79ea71daa6e287 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 051d058

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

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 051d05897380c7a2a37acfe49c79ea71daa6e287 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 051d058

Verdict parsed from the review's SHA-scoped output markers for commit 051d05897380c7a2a37acfe49c79ea71daa6e287.

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

@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 17, 2026
@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 17, 2026
@mbriones98

Copy link
Copy Markdown
Contributor Author

Superseded by #21624

@bolichen97
bolichen97 deleted the fix/preview-flags-persist-21396-v2 branch November 6, 2026 07:38
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.

Crewmates feature-preview toggle does not persist (stored only in browser localStorage)

1 participant