Skip to content

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

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

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

Conversation

@mbriones98

@mbriones98 mbriones98 commented Oct 17, 2026 •

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.
    • Per-switch record: each browser also records which switches it has seen the gateway hold (kc-feature-previews-server-backed, with an in-memory copy for when storage is full). A recorded switch that the gateway no longer holds reads as off even before the browser is marked synced, so another switch's failed carry-up cannot send a removed switch back up.
    • 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. When the carry is refused as owner-only (403), it says only the owner can save the switch for everyone, with no reload step, since a reload would be refused the same way.
  • 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".
    • Four 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: non-owner dashboard session (e.g. a QR session) -- chat|crew page -- intended: config saves are owner-only, so it sees every switch the owner set (the config GET is not owner-gated), its own toggle is refused and switched back with the owner-only notice, and a switch it had already turned on in that browser stays on there | featurePreviewsSectionNotice.test.tsx "names the %s switch when the owner-only write is refused", "names the owner, not a reload, when a one-time carry is refused as owner-only"
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 (33 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;
    • a switch the gateway held and then dropped reads as off when another switch's carry-up failed, also when the per-switch record cannot be stored, and the browser-only switch stays on;
    • an unreadable per-switch record reads as empty;
    • 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;
    • the per-switch record check, and its in-memory copy.
  • website/src/test/previewSurfaces.test.tsx: the section shows the owner-only notice naming the switch when the PATCH returns 403.

  • website/src/test/featurePreviewsSectionNotice.test.tsx (11 tests), with the sync mounted as the shell mounts it:

    • a 403 on each of the 6 switches shows the owner-only notice naming that switch;
    • a 500 shows the "couldn't save" notice;
    • a refused one-time carry says the switch is on in this browser only, and it stays on;
    • a one-time carry refused as owner-only names the owner and has no reload step;
    • the Artifact Deploy and Webhooks links open their pages.

    It lifts FeaturePreviewsSection.tsx above the 80% per-file coverage floor (93.9% of lines locally, across the tests that render it).

  • 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: the preview sync, notice and surfaces tests (79), the src/i18n tests and App boot order (1,023) pass on this commit. The full vitest suite passed (3,073 of 3,073 files) on the previous cut, which this commit changes only in usePreviewFlagServerSync.ts and its test. tsc (app), eslint src/ --max-warnings 0 and jscpd are clean. i18n-check.mjs and the src/i18n tests, including the [changed-values] French and Korean style checks, pass with I18N_BASE_REF set to the base commit.
    • Backend: test_feature_previews_config.py, test_facade_mirror_guards.py, test_config_baseline.py and test_change_card_setting_classes.py pass (116). The full backend run on the previous cut matched origin/main's failure set on this host, which come from the host itself (enterprise profile, live KIROCREW_HOME, 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 the PATCH returning 500, flipping Webhooks puts it back and the notice says it couldn't be saved.
  • 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 toggle refused with 500 (the same notice shows for an expired session's 403), naming the switch:

Couldn't save notice naming Webhooks

A browser-only switch whose carry-up failed:

On in this browser only notice

A browser-only switch whose carry-up was refused as owner-only (403): the switch stays on, the notice names the owner and has no reload step:

Owner-only carry-up notice, switch still on

Related Issues

Fixes #21396

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

Supersedes #21624, #21602 and #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. Each browser records
which switches it has seen the gateway hold, so a switch removed there
reads as off even when another switch's carry-up failed.

Fixes #21396
@mbriones98
mbriones98 requested review from a team and KiroCrewCaptain as code owners October 17, 2026 23:54
@mbriones98
mbriones98 enabled auto-merge (squash) October 17, 2026 23:54
@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 7ee15b8b852886ec2c392d05101e59c986f468cc — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the one-time carry-up code (carried, kc-feature-previews-synced, kc-feature-previews-server-backed) has a planned removal; nothing in this PR ends it.

Suggestions

  • Add a code comment or tracking issue saying when reconcilePreviewFlags's cache-only-ON branch and the two kc-feature-previews-* markers can be deleted. Once browsers have carried their switches up, the gateway is the only source of truth and that client-side migration is dead weight.

[DESIGN-REVIEWED] 7ee15b8

Description read

[DESCRIPTION-READ] 3680783422f56aeccc81fca537e9b07503152ffe84b7b31c2fb01063feec4aef

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

UX Review (Opus 5.5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

Two owner-only notices that look the same give opposite outcomes, and the browser-only notice tells users to reload, which the blind reader was afraid to do.

Watch

  • Same 403, opposite results (shots 2 and 5). feature_previews_save_denied says the switch "was switched back". feature_previews_carry_denied says it "stays on in this browser only". The only thing that decides which one appears is whether the user just clicked or a background carry-up ran, and the user can't see that. The blind reader: "same problem… with opposite results. I can't tell which one is right, or what decides it." This happens every time a non-owner meets either path. It confuses people but doesn't stop them. Fix: open the carry notice with its cause, e.g. "“{{name}}” was turned on earlier in this browser only…".
  • The reload step scares users (shot 4). feature_previews_carry_failed ends with "Reload the page to try again." The reader: "I don't know if reloading turns it on for everyone or switches it off… I wouldn't reload, in case I lose it." Users who don't act leave the switch unsaved for everyone. This only happens on a rare failure, but the switch stays unsaved until they reload. Fix: say that reloading keeps the switch on, e.g. "Reload the page to try saving it again; it stays on here either way."
  • The notice can sit far from the switch. The notice renders once, under the intro. When a lower card such as Folder conductor is refused, its switch quietly flips back while the explanation appears several cards above it. This is rare, but when it happens the user sees no reason for the change. Fix: scroll the notice into view when it appears, or render it inside the refused card.

Suggestions

  • In feature_previews_save_failed, replace "Try again." with "Turn it on again to retry." The reader read "Try again" as a button that isn't there.

[UX-REVIEWED] 7ee15b8

Description read

[DESCRIPTION-READ] df8cc0e26e87c29787ce7e71481856e4e394fbc516cd9611ce52504b387070f4

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 7ee15b8b852886ec2c392d05101e59c986f468cc — 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

A second per-switch localStorage record, plus an in-memory copy of it, guards a third-order edge case that the sync marker already mostly covers.

Not justified as shipped

  • Item 5 — oversized: kc-feature-previews-server-backed with documentBacked exists only for one case: a config key the operator deleted by hand while another switch's carry-up failed in a browser that has not synced yet. Toggles always write an explicit false, so a key goes absent only when someone edits config.json by hand, and PREVIEW_FLAGS_SYNCED_KEY already covers that case once the browser has synced.
    Subtraction: delete PREVIEW_FLAGS_SERVER_BACKED_KEY, documentBacked, serverBacked() and markServerBacked() in usePreviewFlagServerSync.ts, and let reconcile read the sync marker alone.
    Clears when: the record is removed, or a reported case shows a dropped switch coming back in a browser that had already synced.

What this change ships

Inventory (10 items) — 9 justified

Intent: keep a Feature previews switch on in every browser and in the desktop app that use the same gateway. FIX.

  1. Preview switches are saved on the gateway and read back on every surface — justified
  2. dashboard.feature_previews.<name>: six bools, accepted by the PATCH allowlist and the loader — justified
  3. A non-owner session's toggle is refused and switched back with an owner-only notice — justified
  4. A switch on in one browser only is carried up once with if_unset — justified
  5. A per-switch "server held this" record, kept in storage and in memory — oversized
  6. After syncing, a switch on only in the cache reads as off — justified
  7. The retired Remote crew sessions ON is carried up as Chat on a crew — justified
  8. Quick repeated toggles are sent in click order — justified
  9. One section notice naming the refused switch, in four wordings — justified
  10. The section description drops "per-device" and says the switches are saved for everyone — justified

[FIRST-PRINCIPLES-REVIEWED] 7ee15b8

Description read

[DESCRIPTION-READ] 847bdeb2dbc3b14c8cecf1a19a0a34f44c10b85595d666b820819672f6cf19fc

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

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 7ee15b8

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

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

@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 7ee15b8b852886ec2c392d05101e59c986f468cc and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7ee15b8

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

@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 18, 2026
…used as owner-only

A one-time carry-up refused with 403 told the user to reload, but a
reload sends the same request and is refused again. The notice now says
only the owner can save the switch for everyone and that it stays on in
this browser.
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention 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 readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 18, 2026
@mbriones98

Copy link
Copy Markdown
Contributor Author

Superseded by #22000 (same change as one commit off current main, after the conflict with #21953).

@mbriones98 mbriones98 closed this Oct 19, 2026
auto-merge was automatically disabled October 19, 2026 00:33

Pull request was closed

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

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