Skip to content

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

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

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

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: 110 test files (1,651 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. FeaturePreviewsSection.tsx is at 93.9% of lines and usePreviewFlagServerSync.ts at 100% in that run. tsc (app), eslint --max-warnings 0 on the touched files, check-i18n-strings.mjs, check-i18n-keys.mjs and i18n-check.mjs are clean with I18N_BASE_REF set to the base commit, and the regenerated en-XA has no diff.
    • 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 rebuild, 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 #22000 apart from the shell/appShell.tsx line kept from main, and found nothing Critical or High.

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: Backend Tests (Windows) (1) hits the test_ci_ipv6_routing collect timeout (#21943), and Backend Tests (3.12, 2) hits the test_facade_mirror_guards tree-scan timeout on a slow runner (#22004/#22007). This change touches neither test.

Related Issues

Fixes #21396

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

Replaces #22000, which began conflicting with main after #15370 renamed a value on the useKiroUsageReadout() line in shell/appShell.tsx, right above this change's hook call, and already had the two commits PR Hygiene allows. This is the same change as one commit off current main: it keeps main's version of that line and calls the sync hook after it. Earlier versions: #21722, #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 21:39
@mbriones98
mbriones98 enabled auto-merge (squash) October 19, 2026 21:39
@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) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

The one-time migration of six preview bools uses a 329-line client-side state machine that never retires.

Watch

  • The migration machinery has no end date. The hook keeps seven module-level stores: pending, tails, baselines, carried, documentBacked, carriesInFlight/carryFailed, and the kc-feature-previews-synced and kc-feature-previews-server-backed markers. Only the carry-up of a value set before this change needs most of them. Every future preview flag will run through that whole path, and nothing records when the browser-only ON stops needing to be carried up. So code meant to cover one migration becomes the permanent shape of six booleans. The next flag added or retired has to reason about synced and server-backed interleavings that only mattered during the transition.
    Clears when: the carry-up and both markers carry a removal condition in previewFlags.ts (for example "delete after release N"), or the design states why reconcile without the markers (server wins; a cache-only ON is carried up once with if_unset, then marked synced either way) loses a browser-only value that matters.

Suggestions

  • After a refused toggle, cache the server value directly instead of tracking baselines. The refetch in settle already gets the gateway's value, and a flag the gateway does not hold reads as off by the new contract.

[DESIGN-REVIEWED] ea33f88

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

UX Review (Opus 5.5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

One cause, "not the owner", has two opposite outcomes: one notice says the switch "was switched back", the other says it "stays on in this browser only". The blind reader couldn't tell why.

Watch

  • Owner notices contradict each other. feature_previews_save_denied says "…so 'Webhooks' was switched back" and the switch turns off. feature_previews_carry_denied says "…so it stays on in this browser only" and the switch stays on. Shots 02 and 05 show both. The reader said: "I can't tell which one will happen to me, or why they differ." The same goes for save_failed ("Try again") next to carry_failed ("Reload the page"). This is a secondary surface, but a non-owner hits it on every toggle. Fix: open the carry notices with the cause, e.g. "'Webhooks' was turned on in this browser before it could be saved for everyone…", so they no longer read as a different response to the same click.
  • The intro now makes users afraid to touch the switches. "saved for everyone using this {{productName}}" left the reader "nervous about touching anything", and they wouldn't turn off Crewmates because "it might affect everyone". This is a single-user tool, so "everyone" suggests other people who mostly don't exist. It shows on every visit to the section. Fix: name the scope the PR actually means: "saved on this {{productName}}, so they stay set in every browser and in the desktop app."

Suggestions

  • Drop askAgent on the two *_denied notices. The agent can't give a non-owner write access, and the reader asked whether the assistant "would try to change the setting anyway."
  • In feature_previews_save_failed, cut "Try again." or replace it with a real retry button. The reader saw it as "plain text, not a button" and planned to flip the switch again themselves.

[UX-REVIEWED] ea33f88

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

First Principles Review (Opus 5.5) — 🔴 BLOCK

Premise-level review of ea33f887350c0726108d3ccecc2fecbbe99c11fa — 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: BLOCK

The write queue in usePreviewFlagServerSync.ts re-implements the repo's existing optimistic config-path writer instead of using it, and the one-time carry-up adds two localStorage keys to save a single re-click.

Not justified as shipped

  • Item 3 — duplicate of website/src/pages/settings/useOptimisticConfigPaths.ts: pending/tails/baselines/settle handle in-flight protection, supersede, revert and refetch. That hook already does this for 9 consumers. writeIntoCachedBody is a second copy of setConfigPathValue.
    Subtraction: delete writeIntoCachedBody and the queue maps, and use setConfigPathValue plus mutationOpts, as chat-sidebar/sessionSort.ts does.
    Clears when: the write path goes through useOptimisticConfigPaths/setConfigPathValue.
  • Item 5 — oversized: without the carry-up, a browser-only ON is dropped once and the operator turns it on again with one click. sessionSort.ts does its own ifUnset carry-over with no marker. This PR adds kc-feature-previews-synced, kc-feature-previews-server-backed, documentBacked, carriesInFlight/carryFailed and two carry notice strings.
    Subtraction: drop the marker, the per-switch record and the carry notices. Either "server absent → off", or the single carry-over sessionSort.ts uses.
    Clears when: the mechanism is removed, or a human amends the Goal.

What this change ships

Inventory (8 items) — 6 justified

Intent: a preview switch stays on across browsers and the desktop app on one gateway. This is a FIX (#21396).

  1. Preview switches are stored in the gateway config under dashboard.feature_previews.* — justified
  2. A switch flipped on one surface shows up on the others without a reload — justified
  3. Toggles are saved in click order, and a refused toggle switches back — duplicate of useOptimisticConfigPaths.ts
  4. A refused toggle shows a notice naming the switch (owner-only, or save failed) — justified
  5. A switch on in this browser only is carried up once, tracked by sync/record keys — oversized
  6. A non-owner session can no longer keep its own per-browser toggle — justified
  7. The section copy no longer says "per-device" — justified
  8. The PATCH allowlist accepts only the six known names, typed bool — justified

Blockers

  • Duplicates the existing optimistic config-path writer. writeIntoCachedBody rebuilds the path that setConfigPathValue (useOptimisticConfigPaths.ts:11) already builds. pending/baselines/settle repeat that hook's token-guarded in-flight and settle logic. I counted 9 non-test importers of useOptimisticConfigPaths. Subtraction: route the writes through it.
    Clears when: the write path goes through useOptimisticConfigPaths/setConfigPathValue.

[FIRST-PRINCIPLES-REVIEWED] ea33f88

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

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ea33f88

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ea33f887350c0726108d3ccecc2fecbbe99c11fa: <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 ea33f887350c0726108d3ccecc2fecbbe99c11fa — this comment is updated in place on each push.

Review details

No findings that block the merge.

FINDING — docs/system-specs/modules/learn-cron-dashboard.md:4980 — the spec that owns this code still says a preview flag is "the localStorage key of a per-device opt-in", but this PR makes the gateway's dashboard.feature_previews.<name> the stored value and localStorage only a cache. AGENTS.md requires the owning spec to change in the same commit, so the next change made from the spec would treat the switches as browser-only. → Fix: update the "Preview-gated surfaces" paragraph to say the flags are stored in gateway config, with localStorage as a synchronous cache synced by usePreviewFlagServerSync.

[OPUS-REVIEWED] ea33f88

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

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 19, 2026
…sist-21396-v6

# Conflicts:
#	src/kiro_crew/dashboard/handlers/core.py
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 20, 2026
@mbriones98

Copy link
Copy Markdown
Contributor Author

Superseded by #22544, the same change rebuilt as one commit off current main, with the cache write using the shared setConfigPathValue helper.

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

Pull request was closed

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 20, 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.

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

1 participant