Skip to content

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

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

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

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 talks to the same gateway.

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, and 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, the same as every other dashboard setting in config.
  • No change to the DURABLE_PREF_KEYS / /api/ui-prefs backup, so there is one source of truth.

What changed (motivation → approach → change)

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

Approach: the gateway config keeps each switch, and localStorage stays as a fast cache. I chose config over adding the keys to DURABLE_PREF_KEYS because 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.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, the change card classifies them, 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. Afterwards a kc-feature-previews-synced marker makes a cache-only ON read as off, so a key the operator removed on the gateway stays off.
    • Refused toggle: the switch goes back to the stored value, and the section shows an error notice. On a 403 it says only the gateway owner can change feature previews; any other failure says the save failed.
  • Copy: the section description no longer says "per-device" and now says the gateway keeps the switches. Two new strings for the notice. 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 with a false default, 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. After the first sync, 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 (19 tests). The repro: Crewmates turns on from the server when localStorage is empty, and it fails with the sync disabled. The other tests cover:
    • the server copy winning over a stale cache;
    • writes, in-flight protection, and rapid toggles applied in click order;
    • a refused write being put right;
    • an unreadable config keeping the cache;
    • the one-time if_unset carry-up, not replacing a stored value, and not retrying a refused carry;
    • a dropped key reading off once synced;
    • the retired key;
    • error reporting (403 is owner-only, other failures are a failed save, the next accepted toggle clears it, a refused carry is not reported);
    • a parity check that PREVIEW_FLAGS equals every declared flag constant.
  • website/src/test/previewSurfaces.test.tsx: the section renders the owner-only notice when the PATCH returns 403.
  • test/test_feature_previews_config.py: the gateway flag list matches the dashboard flags, nothing is on by default, and the loader keeps only known names with bool values. It also checks that each switch is writable through the PATCH, that an unknown name or a non-bool writes nothing, that if_unset never replaces a stored switch, and that a non-owner cannot write a switch.
  • Local runs:
    • Frontend: full vitest suite, 3,060 files passed. tsc (app) and eslint are clean. lint:i18n, i18n-check and check-i18n-keys pass.
    • Backend: 6,364 passed across the config, change-card, handlers and docs test files. 19 failed or errored the same way on origin/main on this host (test_dashboard_gallery_dispatch_tree.py, test_home_pin_survives_monkeypatch_undo.py: the host resolves an enterprise profile and a live KIROCREW_HOME), so they are unrelated.
    • Repo gates and linters: black, isort and flake8 are clean on the changed Python. The comment-history gate and the file-line-cap gate pass.
  • Local AI review: GPT and Opus read-only reviews ran on the first cut (7a05257; both quoted that SHA). Neither found anything Critical or High. This revision fixes their Medium/advisory findings: write ordering, the carry-up undoing an operator reset, the retired key being carried up, the parity test gap, and silent refusals. The review briefs used the skill's fallback charters because local_review.py refused to build them (__MERGE_BASE__ unmapped).

Manual verification

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

  • Crewmates shows on with an empty localStorage.
  • Flipping Webhooks shows the owner-only notice, and the switch goes back.

Screenshots / video

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

Feature previews section with Crewmates on from the gateway

A toggle refused with 403:

Owner-only notice after a refused toggle

Related Issues

Fixes #21396

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

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
says why next to the switches.

Fixes #21396
@mbriones98
mbriones98 requested review from a team and KiroCrewCaptain as code owners October 17, 2026 09:01
@mbriones98
mbriones98 enabled auto-merge (squash) October 17, 2026 09:01
@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 labels Oct 17, 2026
…sist-21396

# Conflicts:
#	src/kiro_crew/config/loader.py
#	website/src/pages/settings/FeaturePreviewsSection.tsx
@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of fbf3982aab6e6cdfe551b7dec8d0ca3c6f60daa4 — 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, which can no longer turn a preview on locally, is an accepted loss.

[DESIGN-REVIEWED] fbf3982

Description read

[DESCRIPTION-READ] e64a76641a2ad85ae12546577312114d732312390170fd15c2cd5ab925b6c34d

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of fbf3982aab6e6cdfe551b7dec8d0ca3c6f60daa4 — 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 PR reverses a recorded decision that preview switches belong to one device. The only evidence given is the symptom, not a case that the decision was wrong.

Not justified as shipped

  • Item 2 — inherited: the diff deletes the pin "Deliberately localStorage, not backend config: this is a per-device 'show me the unfinished thing' switch … Putting it in config.json would imply a fleet-wide setting and a backend contract that does not exist". The description answers it only with "Root cause: localStorage was the only copy". That restates the per-device choice as a bug and does not show that a gateway-wide scope is what operators want. No docs/decisions/ entry covers preview-flag scope (grepped preview: 0 hits).
    Clears when: Crewmates feature-preview toggle does not persist (stored only in browser localStorage) #21396 or a maintainer comment states that a switch should follow the gateway rather than the device.

What this change ships

Inventory (8 items) — 7 justified

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

  1. A preview switch turned on in one browser shows on in other browsers and in the desktop app — justified
  2. The switch's scope changes from per-device to gateway-wide for every surface — inherited
  3. A non-owner's toggle is refused and the switch goes back — justified
  4. An error notice explains a refused toggle (2 new strings × 12 catalogs) — justified
  5. A switch set only in this browser before the change is carried up to the gateway once (if_unset) — justified
  6. After the first sync, an ON held only in the browser cache reads as off — justified
  7. The retired Remote crew sessions switch is carried up as Chat on a crew, then cleared — justified
  8. New dashboard.feature_previews.<name> config keys, schema entries and docs — justified

[FIRST-PRINCIPLES-REVIEWED] fbf3982

Description read

[DESCRIPTION-READ] 5a9fcebaee1643a97ffcf02c144d444e9a44aec99ea9c4db2d151bd4ccfe1bbb

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

The refusal notice appears only at the top of the section and never names the switch that went back, so users who scroll down may never see why their click undid itself.

Watch

  • Refusal feedback is far from the click. The ErrorNotice is drawn once, under the intro paragraph ({writeError && (<ErrorNotice … className="mb-2" />)}). Flipping a lower card such as Folder conductor or Chat on a crew snaps the switch back, and the reason can sit off-screen above. The blind reader said it "doesn't say which switch I tried to change, and nothing on the page shows which one 'was put back'." This happens on every refused toggle for anyone who is not the owner. Smallest fix: render the notice inside the card whose switch was refused (the hook already knows which flag), or name that flag in the message.
  • "Gateway" is unexplained jargon in both new strings. The blind reader rated the intro "a guess (I don't know what 'the gateway' is)" and said of the error: "I don't know… who the 'gateway owner' is", and "whether the owner is me". Every first-time reader of this section meets this. Smallest fix: talk about what the user sees, e.g. "These switches are saved for everyone using this Kiro Crew, in every browser and the desktop app." and "Only the owner of this Kiro Crew can change feature previews."

Suggestions

  • feature_previews_desc: move the new sentence about where switches are saved so it comes right after "Unreleased features and pages." It is the change this PR ships, and the rest of the paragraph pushes it to the end.

[UX-REVIEWED] fbf3982

Description read

[DESCRIPTION-READ] efe342cbbe9fa87187db589b7b34808e121f88cd79a050a8c2bad99119266bf9

That sha256 names everything this verdict read: the PR description, plus the 5 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 removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings that block the merge.

FINDING — website/src/hooks/usePreviewFlagServerSync.ts:181 — A refused toggle can stay ON while the notice says "The switch was put back". This happens in a non-owner session (PATCH gets 403 from require_owner_dashboard_request, GET still works) in a browser that has an old browser-only ON. That browser's one-time carry fails, so carryFailed stays true and markSynced never runs. When the user then switches another flag ON, the refetch goes to reconcilePreviewFlags, which carries that flag (persist(qc, flag, true, true)) instead of resetting the cache. The carry is refused too, so the cache stays ON on every later load. → Fix: when a user toggle (!ifUnset) is refused, carried.add(flag) and cachePreviewFlag(flag, !on) unless the server holds a boolean for the flag, so reconcile does not treat the refused value as an old browser-only ON.

[OPUS-REVIEWED] fbf3982

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

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

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging fbf3982aab6e6cdfe551b7dec8d0ca3c6f60daa4. Adjudication upheld 1 of 1 blocking finding(s); those must be resolved before merging.

This comment is updated in place on each push.

BLOCKING -- website/src/pages/settings/FeaturePreviewsSection.tsx:173 -- Record the error notice’s hand-off decision
<ErrorNotice
Toggle PATCH returns 500 -> persist() sets writeError -> the notice renders with default askAgent=false, without any sanctioned hand-off decision.
Anchor: errors-use-error-notice
Fix: Explicitly choose askAgent if navigation is safe, or add a No hand-off: comment naming the concrete unsaved draft protected.

[BLOCK-MERGE] fbf3982
[GPT-REVIEWED] fbf3982

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

I'm keeping F1 blocking: the base-branch rule it cites is marked blocking: true, so its flag outranks any weighing of harm against fix cost.

F1: I confirmed the condition in the code. At website/src/pages/settings/FeaturePreviewsSection.tsx:172-180, the ErrorNotice that appears when a write fails has no askAgent, no No hand-off: comment, no sibling ErrorNoticeMenuItem and no noHandoffReason. The rule errors-use-error-notice (.review-base-rules/website-AUTOSDE.yaml:622-623, blocking: true) tells the reviewer to block an added or touched ErrorNotice that records none of these hand-off decisions (:686-690). The fix is cheap: add one prop or one comment.

[ADJUDICATION] fbf3982aab6e6cdfe551b7dec8d0ca3c6f60daa4 total=1 uphold=1 downgrade=0
UPHOLD F1 website/src/pages/settings/FeaturePreviewsSection.tsx:173 reason=autosde-blocking-rule
[GPT-ADJUDICATED] fbf3982aab6e6cdfe551b7dec8d0ca3c6f60daa4

False positive or not applicable? A repository writer can comment:
/ai-review override gpt fbf3982aab6e6cdfe551b7dec8d0ca3c6f60daa4: <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
@mbriones98

Copy link
Copy Markdown
Contributor Author

Superseded by #21602

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