Skip to content

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

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

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

Conversation

@mbriones98

@mbriones98 mbriones98 commented Oct 19, 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 shell/appShell.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: 93 test files (1,467 tests) pass on this commit: the preview sync, notice and surfaces tests, the whole src/i18n folder including the style/ French U+202F and Korean checks, and every test that mounts the shell or App (including App.shell.owners). tsc (app), eslint --max-warnings 0 on the touched files, check-i18n-strings.mjs and i18n-check.mjs are clean with I18N_BASE_REF set to the base commit. The backend files are unchanged from fix(dashboard): keep feature-preview switches on the gateway #21722, where the backend suites passed in CI; they were not re-run locally on this host.
    • 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. On this recut, a GPT (gpt-6.1-sol) and an Opus review of the new commit each quoted its SHA, confirmed the diff matches fix(dashboard): keep feature-preview switches on the gateway #21722 apart from the hook moving to shell/appShell.tsx, and found nothing 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

Known unrelated CI failures

These failed on this commit and again on reruns. This change touches none of these tests or the image build.

Related Issues

Fixes #21396

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

Supersedes #21722, which began conflicting with main after #21953 split App.tsx into shell owners and already had the two commits PR Hygiene allows. This is the same change as one commit off current main; the only difference is that the sync hook is now called in shell/appShell.tsx, where main moved the shell's config reader. Earlier versions: #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. A carry-up refused as
owner-only says the switch stays on in this browser only, with no
reload step. 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 19, 2026 00:33
@mbriones98
mbriones98 requested a review from buluoray October 19, 2026 00:33
@mbriones98
mbriones98 enabled auto-merge (squash) October 19, 2026 00:33
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 19, 2026
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Before merge, check that the dashboard's config refresh frame invalidates ['kirocrewConfig']. Cross-surface sync without a reload depends on it.

Suggestions

  • The one-time carry-up code in usePreviewFlagServerSync.ts (the kc-feature-previews-synced marker, the kc-feature-previews-server-backed record and the carry state) will stay in the shell for good unless something says when to remove it. Add a comment naming the release after which the carry-up can be deleted, which leaves just the server-wins reconcile and the ordered writes.

[DESIGN-REVIEWED] a6915d5

Description read

[DESCRIPTION-READ] 65296e7b2063c1e362c8e66575472c1d911ebcbb18c6b0eb82f399aa5b820ec9

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of a6915d5fbc4dcd343d9b2c4859984294bf5d529e — 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 machinery costs far more than the one click it saves a person who already had an unreleased preview on.

Not justified as shipped

  • Item 4 — oversized: the description says "a switch set only in this browser before the gateway kept the switches is carried up once with if_unset". The only harm this removes is one re-toggle of a default-off preview, once per browser. To remove it the hook adds carried, carriesInFlight, carryFailed, kc-feature-previews-synced, kc-feature-previews-server-backed with its in-memory copy documentBacked, two carry notice strings in 13 catalogs, and the retired-key carry into remote_crew_chat.
    Subtraction: delete the carry path in reconcilePreviewFlags, the synced marker, the server-backed record and the two feature_previews_carry_* strings. Let the reconcile apply the server value, or off when the server has none, and keep only the toggle PATCH path.
    Clears when: the carry machinery is removed, or someone names a user for whom re-toggling a preview once is a real loss.

What this change ships

Inventory (6 items) — 5 justified

Intent: keep a feature-preview switch on across every browser and the desktop app that use one gateway. FIX (#21396).

  1. Preview switches are stored gateway-wide under dashboard.feature_previews.* — justified
  2. A toggle is saved to the gateway; writes for one switch go in click order — justified
  3. Every open dashboard picks up the gateway's switch values — justified
  4. A switch that was on in this browser only is carried up once, with the sync and per-switch markers — oversized
  5. A refused toggle switches back and shows an error notice naming the switch — justified
  6. A non-owner session can no longer turn on its own preview — justified

[FIRST-PRINCIPLES-REVIEWED] a6915d5

Description read

[DESCRIPTION-READ] 2a585fbbc8613587d11188e5c8a47f9ea8ff95f9624594eeb14a242db5749fc5

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

All four new notices share one red error box, so "switched back" and "still on, browser only" look the same, and the reader couldn't tell which ones are errors.

Watch

  • Two different outcomes get one warning style. In shot 4, feature_previews_carry_failed / carry_denied say the switch stays on, but they render in the same red ErrorNotice as the "switched back" notices. The blind reader said: "It's confusing that this is red like an error when the switch actually stayed on" and "Same reason, two outcomes… I can't tell why." Every non-owner or offline browser that is upgrading sees this once per switch, and they can't tell whether the feature works. Fix: show the carry notices as a neutral or info notice, and start each message with what happened ("Kept on in this browser only…").
  • "Ask the agent" appears on the owner-only notices. The agent can't give anyone owner rights. The reader asked: "I don't know whether it would message the owner or just the AI, or what the AI could do about permissions." Fix: drop askAgent when writeError.denied.
  • Non-owners only learn they can't change previews after a switch reverts. The intro says "saved for everyone using this Kiro Crew", but every switch still looks usable. The reader said: "nothing on the page told me beforehand that I'm not allowed." It's infrequent (only non-owner sessions), but they get it on every click. Fix: when the session is not the owner, add one line under the intro saying only the owner can change these switches.

Suggestions

  • In feature_previews_carry_failed, say what happens on reload: "Reload the page to try saving it again; it stays on here either way." The reader feared a reload would turn it off.

[UX-REVIEWED] a6915d5

Description read

[DESCRIPTION-READ] 45690a452e48fb5698a573af04eb874159b6d8367514c4fbf6ba991d5ae1a212

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a6915d5

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

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] a6915d5

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable a6915d5fbc4dcd343d9b2c4859984294bf5d529e: <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 19, 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 19, 2026
@mbriones98 mbriones98 closed this Oct 19, 2026
auto-merge was automatically disabled October 19, 2026 18:13

Pull request was closed

@mbriones98 mbriones98 reopened this Oct 19, 2026
@mbriones98
mbriones98 enabled auto-merge (squash) October 19, 2026 18:13
@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 19, 2026
@mbriones98 mbriones98 closed this Oct 19, 2026
auto-merge was automatically disabled October 19, 2026 18:44

Pull request was closed

@mbriones98 mbriones98 reopened this Oct 19, 2026
@mbriones98
mbriones98 enabled auto-merge (squash) October 19, 2026 18:44
@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 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 19, 2026
@mbriones98

Copy link
Copy Markdown
Contributor Author

Superseded by #22298, the same change rebuilt as one commit off current main.

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

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
@bolichen97
bolichen97 deleted the fix/preview-flags-persist-21396-v5 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

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