fix(#2743): automated Cursor CLI fix

application/state/appearanceSync.test.ts

@@ -27,6 +27,7 @@ const systemLight: AppearanceRenderSnapshot = {
   darkUiThemeId: "midnight",
   accentMode: "theme",
   customAccent: "208 100% 50%",
+  customAccentVersion: 0,
 };
 
 test("an OS color event cannot persist a stale System choice over a newer Dark choice", () => {
@@ -97,6 +98,7 @@ test("a non-theme appearance IPC value wins over stale local storage for that ke
     darkUiThemeId: "midnight",
     accentMode: "theme",
     customAccent: "208 100% 50%",
+    customAccentVersion: 0,
   };
   // Storage still lags for every non-theme field (the race the review covers).
   const staleStored: StoredAppearanceValues = {
@@ -151,6 +153,22 @@ test("a non-theme appearance IPC value wins over stale local storage for that ke
   }, customAccentSelection);
   assert.equal(nextCustomAccent.customAccent, "221.2 83.2% 53.3%");
 
+  // Stale lower-version accent echoes must not clobber a newer local drag sample.
+  const afterDrag = {
+    ...current,
+    customAccent: "199 89% 48%",
+    customAccentVersion: 2,
+  };
+  const staleAccentEcho = resolveAppearanceSyncState(afterDrag, {
+    ...staleStored,
+    customAccent: "0 84% 60%",
+  }, {
+    key: STORAGE_KEY_COLOR,
+    value: { color: "0 84% 60%", version: 1 },
+  });
+  assert.equal(staleAccentEcho.customAccent, "199 89% 48%");
+  assert.equal(staleAccentEcho.customAccentVersion, 2);
+
   // Without an announced key, full rehydrate still reads storage.
   const noIncoming = resolveAppearanceSyncState(current, {
     ...staleStored,
@@ -168,6 +186,7 @@ test("sequential keyed appearance IPC updates compose without stale-storage clob
     darkUiThemeId: "midnight",
     accentMode: "theme",
     customAccent: "208 100% 50%",
+    customAccentVersion: 0,
   };
   const staleStored: StoredAppearanceValues = { ...initial };
 
@@ -196,6 +215,7 @@ test("System on a light OS changes to Dark in every open follow-app terminal", (
     darkUiThemeId: systemLight.darkUiThemeId,
     accentMode: systemLight.accentMode,
     customAccent: systemLight.customAccent,
+    customAccentVersion: systemLight.customAccentVersion,
   };
   const terminalAppearance = (appearance: AppearanceState, resolvedTheme: "light" | "dark") => (
     resolveGlobalTerminalAppearance({
@@ -292,7 +312,7 @@ test("the race guards are wired into the real settings paths", () => {
   const lightNotifyIndex = stateSource.indexOf("notifySettingsChanged(STORAGE_KEY_UI_THEME_LIGHT, lightUiThemeId)", writeIndex);
   const darkNotifyIndex = stateSource.indexOf("notifySettingsChanged(STORAGE_KEY_UI_THEME_DARK, darkUiThemeId)", writeIndex);
   const accentModeNotifyIndex = stateSource.indexOf("notifySettingsChanged(STORAGE_KEY_ACCENT_MODE, accentMode)", writeIndex);
-  const colorNotifyIndex = stateSource.indexOf("notifySettingsChanged(STORAGE_KEY_COLOR, customAccent)", writeIndex);
+  const colorNotifyIndex = stateSource.indexOf("notifySettingsChanged(STORAGE_KEY_COLOR, customAccentRecord)", writeIndex);
 
   assert.ok(guardIndex >= 0, "the settings effect must compare persisted appearance fields");
   assert.ok(returnIndex > guardIndex && returnIndex < writeIndex, "the stale render must stop before storage is written");
@@ -301,6 +321,8 @@ test("the race guards are wired into the real settings paths", () => {
   assert.ok(darkNotifyIndex > writeIndex, "dark UI theme changes must be announced over IPC with the new value");
   assert.ok(accentModeNotifyIndex > writeIndex, "accent mode changes must be announced over IPC with the new value");
   assert.ok(colorNotifyIndex > writeIndex, "custom accent changes must be announced over IPC with the new value");
+  assert.match(stateSource, /shouldBroadcastCustomAccentChange/);
+  assert.match(stateSource, /serializeCustomAccentRecord\(customAccentRecord\)/);
   // Source still only notifies fields that actually changed (keyed, not a single theme-only broadcast).
   assert.match(
     stateSource,

application/state/appearanceSync.ts

@@ -6,10 +6,14 @@ import {
   STORAGE_KEY_UI_THEME_LIGHT,
 } from '../../infrastructure/config/storageKeys';
 import {
-  isValidHslToken,
   isValidTheme,
   isValidUiThemeId,
 } from './settingsStateDefaults';
+import {
+  parseCustomAccentRecord,
+  shouldApplyCustomAccentRecord,
+  type CustomAccentRecord,
+} from './customAccentSync';
 
 export type AppearanceState = {
   theme: "light" | "dark" | "system";
@@ -17,6 +21,8 @@ export type AppearanceState = {
   darkUiThemeId: string;
   accentMode: "theme" | "custom";
   customAccent: string;
+  /** Sync revision for custom accent; gates stale IPC/storage echoes during color-picker drag. */
+  customAccentVersion: number;
 };
 
 export type AppearanceRenderSnapshot = {
@@ -50,7 +56,8 @@ export function hasPersistedAppearanceChanged(
     || previous.lightUiThemeId !== current.lightUiThemeId
     || previous.darkUiThemeId !== current.darkUiThemeId
     || previous.accentMode !== current.accentMode
-    || previous.customAccent !== current.customAccent;
+    || previous.customAccent !== current.customAccent
+    || previous.customAccentVersion !== current.customAccentVersion;
 }
 
 export function resolveIncomingAppearanceValue<T>(
@@ -106,13 +113,20 @@ export function resolveAppearanceSyncState(
     current.accentMode,
     (value): value is AppearanceState['accentMode'] => value === 'theme' || value === 'custom',
   );
-  const customAccent = resolveIncomingAppearanceValue(
-    incoming,
-    STORAGE_KEY_COLOR,
-    stored.customAccent,
-    current.customAccent,
-    (value): value is string => typeof value === 'string' && isValidHslToken(value),
-  );
+  const currentAccentRecord: CustomAccentRecord = {
+    color: current.customAccent,
+    version: current.customAccentVersion,
+  };
+  const incomingAccentRaw = incoming?.key === STORAGE_KEY_COLOR ? incoming.value : undefined;
+  const resolvedAccentRaw = incomingAccentRaw !== undefined
+    ? incomingAccentRaw
+    : (incoming ? currentAccentRecord : stored.customAccent);
+  const resolvedAccentRecord = incomingAccentRaw !== undefined || !incoming
+    ? parseCustomAccentRecord(resolvedAccentRaw)
+    : currentAccentRecord;
+  const nextAccentRecord = shouldApplyCustomAccentRecord(currentAccentRecord, resolvedAccentRecord)
+    ? resolvedAccentRecord
+    : currentAccentRecord;
 
   return {
     theme: isValidTheme(theme) ? theme : current.theme,
@@ -123,9 +137,8 @@ export function resolveAppearanceSyncState(
       ? darkUiThemeId
       : current.darkUiThemeId,
     accentMode: accentMode === 'theme' || accentMode === 'custom' ? accentMode : current.accentMode,
-    customAccent: typeof customAccent === 'string' && isValidHslToken(customAccent)
-      ? customAccent.trim()
-      : current.customAccent,
+    customAccent: nextAccentRecord.color,
+    customAccentVersion: nextAccentRecord.version,
   };
 }
 
@@ -165,11 +178,24 @@ export function resolveAppearanceStorageEvent(
     };
   }
   if (key === STORAGE_KEY_COLOR) {
+    if (newValue == null) {
+      return { handled: true, next: current };
+    }
+    const incoming = parseCustomAccentRecord(newValue);
+    const currentRecord: CustomAccentRecord = {
+      color: current.customAccent,
+      version: current.customAccentVersion,
+    };
+    if (!shouldApplyCustomAccentRecord(currentRecord, incoming)) {
+      return { handled: true, next: current };
+    }
     return {
       handled: true,
-      next: newValue && isValidHslToken(newValue)
-        ? { ...current, customAccent: newValue.trim() }
-        : current,
+      next: {
+        ...current,
+        customAccent: incoming.color,
+        customAccentVersion: incoming.version,
+      },
     };
   }
   return { handled: false, next: current };

application/state/customAccentSync.test.ts

@@ -0,0 +1,204 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  parseCustomAccentRecord,
+  serializeCustomAccentRecord,
+  shouldApplyCustomAccentRecord,
+  shouldBroadcastCustomAccentChange,
+  type CustomAccentMutationSource,
+  type CustomAccentRecord,
+} from './customAccentSync.ts';
+
+/**
+ * Minimal model of the settings ↔ main custom-accent sync loop that caused
+ * #2743. Models both IPC rebroadcast and stale localStorage overwrites while
+ * the native color picker fires rapid onChange events.
+ */
+function simulateAccentDrag(options: {
+  shouldBroadcast: (
+    source: CustomAccentMutationSource,
+    persistMounted: boolean,
+  ) => { shouldBroadcast: boolean; nextSource: CustomAccentMutationSource };
+  shouldApply: (current: CustomAccentRecord, incoming: CustomAccentRecord) => boolean;
+  versioned: boolean;
+}): { settingsValues: string[]; mainValues: string[]; storageWrites: string[] } {
+  let settings: CustomAccentRecord = { color: '221.2 83.2% 53.3%', version: 0 };
+  let main: CustomAccentRecord = { color: '221.2 83.2% 53.3%', version: 0 };
+  let settingsSource: CustomAccentMutationSource = 'local';
+  let mainSource: CustomAccentMutationSource = 'local';
+  let storage = options.versioned
+    ? serializeCustomAccentRecord(settings)
+    : settings.color;
+  const settingsValues: string[] = [];
+  const mainValues: string[] = [];
+  const storageWrites: string[] = [];
+
+  const pendingIpc: Array<{ to: 'settings' | 'main'; record: CustomAccentRecord }> = [];
+
+  const writeStorage = (record: CustomAccentRecord) => {
+    const next = options.versioned
+      ? serializeCustomAccentRecord(record)
+      : record.color;
+    if (next === storage) return;
+    storage = next;
+    storageWrites.push(next);
+  };
+
+  const applyLocal = (window: 'settings' | 'main', color: string) => {
+    const bump = (prev: CustomAccentRecord): CustomAccentRecord => (
+      options.versioned
+        ? { color, version: prev.version + 1 }
+        : { color, version: 0 }
+    );
+
+    if (window === 'settings') {
+      settingsSource = 'local';
+      settings = bump(settings);
+      settingsValues.push(settings.color);
+      writeStorage(settings);
+      const decision = options.shouldBroadcast(settingsSource, true);
+      settingsSource = decision.nextSource;
+      if (decision.shouldBroadcast) pendingIpc.push({ to: 'main', record: { ...settings } });
+      return;
+    }
+
+    mainSource = 'local';
+    main = bump(main);
+    mainValues.push(main.color);
+    writeStorage(main);
+    const decision = options.shouldBroadcast(mainSource, true);
+    mainSource = decision.nextSource;
+    if (decision.shouldBroadcast) pendingIpc.push({ to: 'settings', record: { ...main } });
+  };
+
+  const applyIncoming = (window: 'settings' | 'main', record: CustomAccentRecord) => {
+    if (window === 'settings') {
+      if (!options.shouldApply(settings, record)) return;
+      settingsSource = 'incoming';
+      settings = { ...record };
+      settingsValues.push(settings.color);
+      writeStorage(settings);
+      const decision = options.shouldBroadcast(settingsSource, true);
+      settingsSource = decision.nextSource;
+      if (decision.shouldBroadcast) pendingIpc.push({ to: 'main', record: { ...settings } });
+      return;
+    }
+
+    if (!options.shouldApply(main, record)) return;
+    mainSource = 'incoming';
+    main = { ...record };
+    mainValues.push(main.color);
+    writeStorage(main);
+    const decision = options.shouldBroadcast(mainSource, true);
+    mainSource = decision.nextSource;
+    if (decision.shouldBroadcast) pendingIpc.push({ to: 'settings', record: { ...main } });
+  };
+
+  const flushIpc = () => {
+    while (pendingIpc.length > 0) {
+      const next = pendingIpc.shift()!;
+      applyIncoming(next.to, next.record);
+      if (settingsValues.length > 40) break;
+    }
+  };
+
+  const deliverStorageTo = (window: 'settings' | 'main') => {
+    const record = options.versioned
+      ? parseCustomAccentRecord(JSON.parse(storage))
+      : parseCustomAccentRecord(storage);
+    applyIncoming(window, record);
+  };
+
+  applyLocal('settings', '0 84% 60%');
+  deliverStorageTo('main');
+  applyLocal('settings', '199 89% 48%');
+  // Delayed IPC for the older color arrives after the newer local drag sample.
+  const delayed = pendingIpc.shift();
+  flushIpc();
+  if (delayed) applyIncoming(delayed.to, delayed.record);
+  deliverStorageTo('settings');
+  flushIpc();
+
+  return { settingsValues, mainValues, storageWrites };
+}
+
+test('parseCustomAccentRecord accepts legacy HSL tokens and versioned JSON', () => {
+  assert.deepEqual(parseCustomAccentRecord('199 89% 48%'), { color: '199 89% 48%', version: 0 });
+  assert.deepEqual(
+    parseCustomAccentRecord({ color: '0 84% 60%', version: 3 }),
+    { color: '0 84% 60%', version: 3 },
+  );
+  assert.deepEqual(
+    parseCustomAccentRecord('{"color":"262.1 83.3% 57.8%","version":9}'),
+    { color: '262.1 83.3% 57.8%', version: 9 },
+  );
+  assert.equal(parseCustomAccentRecord('bad').color, '221.2 83.2% 53.3%');
+});
+
+test('shouldApplyCustomAccentRecord ignores stale revisions', () => {
+  const current = { color: '199 89% 48%', version: 2 };
+  assert.equal(shouldApplyCustomAccentRecord(current, { color: '0 84% 60%', version: 1 }), false);
+  assert.equal(shouldApplyCustomAccentRecord(current, { color: '330 81% 60%', version: 3 }), true);
+  assert.equal(shouldApplyCustomAccentRecord(current, { color: '199 89% 48%', version: 2 }), false);
+});
+
+test('shouldBroadcastCustomAccentChange suppresses incoming rebroadcasts', () => {
+  assert.deepEqual(
+    shouldBroadcastCustomAccentChange('incoming', true),
+    { shouldBroadcast: false, nextSource: 'local' },
+  );
+  assert.deepEqual(
+    shouldBroadcastCustomAccentChange('local', true),
+    { shouldBroadcast: true, nextSource: 'local' },
+  );
+  assert.deepEqual(
+    shouldBroadcastCustomAccentChange('local', false),
+    { shouldBroadcast: false, nextSource: 'local' },
+  );
+});
+
+test('legacy unversioned always-broadcast accent sync oscillates during a fast drag', () => {
+  const alwaysBroadcast = (
+    _source: CustomAccentMutationSource,
+    persistMounted: boolean,
+  ) => ({
+    shouldBroadcast: persistMounted,
+    nextSource: 'local' as const,
+  });
+  const alwaysApply = () => true;
+
+  const { settingsValues } = simulateAccentDrag({
+    shouldBroadcast: alwaysBroadcast,
+    shouldApply: alwaysApply,
+    versioned: false,
+  });
+  const unique = new Set(settingsValues);
+  assert.ok(
+    unique.has('0 84% 60%') && unique.has('199 89% 48%') && settingsValues.length > 2,
+    `expected oscillation between drag samples, got ${settingsValues.join(' | ')}`,
+  );
+});
+
+test('versioned accent sync ignores stale peer echoes during a fast drag', () => {
+  const { settingsValues, mainValues } = simulateAccentDrag({
+    shouldBroadcast: shouldBroadcastCustomAccentChange,
+    shouldApply: shouldApplyCustomAccentRecord,
+    versioned: true,
+  });
+
+  assert.deepEqual(settingsValues, ['0 84% 60%', '199 89% 48%']);
+  assert.ok(mainValues.includes('199 89% 48%'));
+  assert.equal(
+    mainValues.includes('0 84% 60%') && mainValues[mainValues.length - 1] === '0 84% 60%',
+    false,
+  );
+});
+
+test('serializeCustomAccentRecord round-trips through parse', () => {
+  const raw = serializeCustomAccentRecord({ color: '262.1 83.3% 57.8%', version: 9 });
+  assert.deepEqual(parseCustomAccentRecord(JSON.parse(raw)), {
+    color: '262.1 83.3% 57.8%',
+    version: 9,
+  });
+});

application/state/customAccentSync.ts

@@ -0,0 +1,93 @@
+import { DEFAULT_CUSTOM_ACCENT, isValidHslToken } from './settingsStateDefaults';
+
+export type CustomAccentMutationSource = 'local' | 'incoming';
+
+export type CustomAccentRecord = {
+  color: string;
+  version: number;
+};
+
+const FALLBACK_RECORD: CustomAccentRecord = {
+  color: DEFAULT_CUSTOM_ACCENT,
+  version: 0,
+};
+
+function normalizeAccentColor(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  return isValidHslToken(trimmed) ? trimmed : null;
+}
+
+/**
+ * Parse persisted / IPC custom-accent payloads.
+ * Accepts legacy plain HSL tokens ("221.2 83.2% 53.3%") and versioned records.
+ */
+export function parseCustomAccentRecord(raw: unknown): CustomAccentRecord {
+  if (typeof raw === 'string') {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('{')) {
+      try {
+        return parseCustomAccentRecord(JSON.parse(trimmed));
+      } catch {
+        // fall through to plain HSL
+      }
+    }
+    const color = normalizeAccentColor(trimmed);
+    if (color) return { color, version: 0 };
+  }
+
+  if (raw && typeof raw === 'object') {
+    const record = raw as { color?: unknown; version?: unknown };
+    const color = normalizeAccentColor(record.color) ?? FALLBACK_RECORD.color;
+    const version = Number(record.version);
+    return {
+      color,
+      version: Number.isFinite(version) && version > 0 ? Math.floor(version) : 0,
+    };
+  }
+
+  return { ...FALLBACK_RECORD };
+}
+
+export function serializeCustomAccentRecord(record: CustomAccentRecord): string {
+  const color = normalizeAccentColor(record.color) ?? FALLBACK_RECORD.color;
+  return JSON.stringify({
+    color,
+    version: Math.max(0, Math.floor(record.version) || 0),
+  });
+}
+
+/**
+ * Incoming peer updates must not clobber a newer local/drag revision.
+ * Equal versions are treated as already-applied (no state thrash).
+ */
+export function shouldApplyCustomAccentRecord(
+  current: CustomAccentRecord,
+  incoming: CustomAccentRecord,
+): boolean {
+  if (incoming.version > current.version) return true;
+  if (incoming.version < current.version) return false;
+  // Same version: only apply when the color itself differs and both are
+  // legacy/unversioned (version 0), so first-load plain strings still sync.
+  if (incoming.version === 0 && current.version === 0) {
+    return incoming.color !== current.color;
+  }
+  return false;
+}
+
+/**
+ * Decide whether a custom-accent state change should be rebroadcast to peer
+ * windows. Incoming IPC/storage updates must not notify again — otherwise a
+ * fast native color-picker drag in the settings window ping-pongs with the
+ * main window and the accent CSS variables oscillate (see #2743, same class
+ * as window-opacity #2018).
+ */
+export function shouldBroadcastCustomAccentChange(
+  mutationSource: CustomAccentMutationSource,
+  persistMounted: boolean,
+): { shouldBroadcast: boolean; nextSource: CustomAccentMutationSource } {
+  if (mutationSource === 'incoming') {
+    return { shouldBroadcast: false, nextSource: 'local' };
+  }
+  return { shouldBroadcast: persistMounted, nextSource: 'local' };
+}

application/state/settingsStorageSync.ts

@@ -66,6 +66,7 @@ interface UseSettingsStorageSyncParams {
   darkUiThemeId: string;
   accentMode: 'theme' | 'custom';
   customAccent: string;
+  customAccentVersion: number;
   customCSS: string;
   uiFontFamilyId: string;
   hotkeyScheme: HotkeyScheme;
@@ -109,7 +110,7 @@ interface UseSettingsStorageSyncParams {
   setLightUiThemeId: Dispatch<SetStateAction<string>>;
   setDarkUiThemeId: Dispatch<SetStateAction<string>>;
   setAccentMode: Dispatch<SetStateAction<'theme' | 'custom'>>;
-  setCustomAccent: Dispatch<SetStateAction<string>>;
+  applyIncomingCustomAccent: (raw: unknown) => void;
   setCustomCSS: Dispatch<SetStateAction<string>>;
   setUiFontFamilyId: Dispatch<SetStateAction<string>>;
   setHotkeyScheme: Dispatch<SetStateAction<HotkeyScheme>>;
@@ -160,7 +161,7 @@ interface UseSettingsStorageSyncParams {
 
 export function useSettingsStorageSync({
   enabled = true,
-  theme, lightUiThemeId, darkUiThemeId, accentMode, customAccent,
+  theme, lightUiThemeId, darkUiThemeId, accentMode, customAccent, customAccentVersion,
   customCSS, uiFontFamilyId, hotkeyScheme, uiLanguage,
   terminalThemeId, followAppTerminalTheme, terminalFontFamilyId, terminalFontSize,
   sftpDoubleClickBehavior, sftpAutoSync, sftpShowHiddenFiles,
@@ -168,7 +169,7 @@ export function useSettingsStorageSync({
   showRecentHosts, hostClickBehavior, showOnlyUngroupedHostsInRoot, showSftpTab, showHostTreeSidebar, terminalSidePanelAutoOpen, terminalSidePanelAutoOpenTab, shellOnlyTabNumberShortcuts, disableTerminalFontZoom, restorePreviousSession, restoreTerminalCwd,
   editorWordWrap, sessionLogsEnabled, sessionLogsDir, sessionLogsFormat, sessionLogsTimestampsEnabled, sshDebugLogsEnabled, sshDeepLinkEnabled, jmsDeepLinkEnabled, explorerContextMenuEnabled,
   globalHotkeyEnabled, autoUpdateEnabled, windowOpacity, appIconVariant,
-  setTheme, setLightUiThemeId, setDarkUiThemeId, setAccentMode, setCustomAccent,
+  setTheme, setLightUiThemeId, setDarkUiThemeId, setAccentMode, applyIncomingCustomAccent,
   setCustomCSS, setUiFontFamilyId, setHotkeyScheme, setUiLanguage,
   setTerminalThemeId, setTerminalThemeDarkId, setTerminalThemeLightId,
   setFollowAppTerminalThemeState, setTerminalFontFamilyId, setTerminalFontSize,
@@ -184,7 +185,7 @@ export function useSettingsStorageSync({
   // can compare without capturing 25+ state variables in its closure / dep array.
   // This avoids constant listener detach/reattach on every state change.
   const settingsSnapshotRef = useRef({
-    theme, lightUiThemeId, darkUiThemeId, accentMode, customAccent,
+    theme, lightUiThemeId, darkUiThemeId, accentMode, customAccent, customAccentVersion,
     customCSS, uiFontFamilyId, hotkeyScheme, uiLanguage,
     terminalThemeId, followAppTerminalTheme, terminalFontFamilyId, terminalFontSize,
     sftpDoubleClickBehavior, sftpAutoSync, sftpShowHiddenFiles,
@@ -194,7 +195,7 @@ export function useSettingsStorageSync({
     globalHotkeyEnabled, autoUpdateEnabled, windowOpacity, appIconVariant,
   });
   settingsSnapshotRef.current = {
-    theme, lightUiThemeId, darkUiThemeId, accentMode, customAccent,
+    theme, lightUiThemeId, darkUiThemeId, accentMode, customAccent, customAccentVersion,
     customCSS, uiFontFamilyId, hotkeyScheme, uiLanguage,
     terminalThemeId, followAppTerminalTheme, terminalFontFamilyId, terminalFontSize,
     sftpDoubleClickBehavior, sftpAutoSync, sftpShowHiddenFiles,
@@ -215,7 +216,15 @@ export function useSettingsStorageSync({
         if (appearance.next.lightUiThemeId !== s.lightUiThemeId) setLightUiThemeId(appearance.next.lightUiThemeId);
         if (appearance.next.darkUiThemeId !== s.darkUiThemeId) setDarkUiThemeId(appearance.next.darkUiThemeId);
         if (appearance.next.accentMode !== s.accentMode) setAccentMode(appearance.next.accentMode);
-        if (appearance.next.customAccent !== s.customAccent) setCustomAccent(appearance.next.customAccent);
+        if (
+          appearance.next.customAccent !== s.customAccent
+          || appearance.next.customAccentVersion !== s.customAccentVersion
+        ) {
+          applyIncomingCustomAccent({
+            color: appearance.next.customAccent,
+            version: appearance.next.customAccentVersion,
+          });
+        }
         return;
       }
       if (e.key === STORAGE_KEY_CUSTOM_CSS && e.newValue !== null) {
@@ -505,7 +514,7 @@ export function useSettingsStorageSync({
     mergeIncomingTerminalSettings,
     setAccentMode,
     setAutoUpdateEnabled,
-    setCustomAccent,
+    applyIncomingCustomAccent,
     setCustomCSS,
     setDarkUiThemeId,
     setEditorWordWrapState,

application/state/useSettingsState.ts

@@ -88,7 +88,6 @@ import { resolveSftpTransferConcurrency } from './sftp/transferConcurrency';
 import { resolveSshTransportIdleTtlMs } from '../../infrastructure/config/sshTransportIdleTtl';
 import {
   DEFAULT_ACCENT_MODE,
-  DEFAULT_CUSTOM_ACCENT,
   DEFAULT_DARK_UI_THEME,
   DEFAULT_EDITOR_WORD_WRAP,
   DEFAULT_HOTKEY_SCHEME,
@@ -154,6 +153,14 @@ import {
   type WindowOpacityMutationSource,
   type WindowOpacityRecord,
 } from './windowOpacitySync';
+import {
+  parseCustomAccentRecord,
+  serializeCustomAccentRecord,
+  shouldApplyCustomAccentRecord,
+  shouldBroadcastCustomAccentChange,
+  type CustomAccentMutationSource,
+  type CustomAccentRecord,
+} from './customAccentSync';
 import {
   createLocalTerminalFontSizeRecord,
   createTerminalFontSizeSyncOrigin,
@@ -193,15 +200,47 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
     const stored = readStoredString(STORAGE_KEY_UI_THEME_DARK);
     return stored && isValidUiThemeId('dark', stored) ? stored : DEFAULT_DARK_UI_THEME;
   });
-  const [customAccent, setCustomAccent] = useState<string>(() => {
-    const stored = readStoredString(STORAGE_KEY_COLOR);
-    return stored && isValidHslToken(stored) ? stored.trim() : DEFAULT_CUSTOM_ACCENT;
+  const [customAccentRecord, setCustomAccentRecord] = useState<CustomAccentRecord>(() => {
+    return parseCustomAccentRecord(readStoredString(STORAGE_KEY_COLOR));
   });
+  const customAccent = customAccentRecord.color;
+  const customAccentMutationSourceRef = useRef<CustomAccentMutationSource>('local');
+  const setCustomAccent = useCallback((nextValue: SetStateAction<string>) => {
+    customAccentMutationSourceRef.current = 'local';
+    setCustomAccentRecord((prev) => {
+      const candidate = typeof nextValue === 'function'
+        ? (nextValue as (prevState: string) => string)(prev.color)
+        : nextValue;
+      const next = parseCustomAccentRecord(candidate);
+      if (next.color === prev.color) return prev;
+      return { color: next.color, version: prev.version + 1 };
+    });
+  }, []);
+  const applyIncomingCustomAccent = useCallback((raw: unknown) => {
+    const incoming = parseCustomAccentRecord(raw);
+    setCustomAccentRecord((prev) => {
+      if (!shouldApplyCustomAccentRecord(prev, incoming)) {
+        return prev;
+      }
+      customAccentMutationSourceRef.current = 'incoming';
+      return incoming;
+    });
+  }, []);
   const [accentMode, setAccentMode] = useState<'theme' | 'custom'>(() => {
     const stored = readStoredString(STORAGE_KEY_ACCENT_MODE);
     if (stored === 'theme' || stored === 'custom') return stored;
-    const legacyColor = readStoredString(STORAGE_KEY_COLOR);
-    return legacyColor && isValidHslToken(legacyColor) ? 'custom' : DEFAULT_ACCENT_MODE;
+    const raw = readStoredString(STORAGE_KEY_COLOR);
+    if (!raw) return DEFAULT_ACCENT_MODE;
+    if (isValidHslToken(raw.trim())) return 'custom';
+    if (raw.trim().startsWith('{')) {
+      try {
+        const obj = JSON.parse(raw.trim()) as { color?: unknown };
+        return typeof obj.color === 'string' && isValidHslToken(obj.color) ? 'custom' : DEFAULT_ACCENT_MODE;
+      } catch {
+        return DEFAULT_ACCENT_MODE;
+      }
+    }
+    return DEFAULT_ACCENT_MODE;
   });
   const [uiFontFamilyId, setUiFontFamilyId] = useState<string>(() => {
     const stored = readStoredString(STORAGE_KEY_UI_FONT_FAMILY);
@@ -556,6 +595,7 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
     darkUiThemeId,
     accentMode,
     customAccent,
+    customAccentVersion: customAccentRecord.version,
   });
   appearanceStateRef.current = {
     theme,
@@ -563,6 +603,7 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
     darkUiThemeId,
     accentMode,
     customAccent,
+    customAccentVersion: customAccentRecord.version,
   };
 
   const setTerminalSettings = useCallback((nextValue: SetStateAction<TerminalSettings>) => {
@@ -732,6 +773,7 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
       darkUiThemeId: nextDarkId,
       accentMode: nextAccentMode,
       customAccent: nextAccent,
+      customAccentVersion: nextAccentVersion,
     } = nextAppearance;
 
     // Fix 2: Skip expensive DOM operations if nothing actually changed
@@ -740,18 +782,27 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
       nextLightId === current.lightUiThemeId &&
       nextDarkId === current.darkUiThemeId &&
       nextAccentMode === current.accentMode &&
-      nextAccent === current.customAccent
+      nextAccent === current.customAccent &&
+      nextAccentVersion === current.customAccentVersion
     ) {
       return;
     }
 
     // Publish synchronously so a later keyed IPC in the same turn composes on top.
     appearanceStateRef.current = nextAppearance;
+    if (
+      nextAccent !== current.customAccent
+      || nextAccentVersion !== current.customAccentVersion
+    ) {
+      // Mark incoming so the persist effect does not rebroadcast to the peer that
+      // originated this update (color-picker drag ping-pong; see #2743).
+      customAccentMutationSourceRef.current = 'incoming';
+      setCustomAccentRecord({ color: nextAccent, version: nextAccentVersion });
+    }
     setTheme(nextTheme);
     setLightUiThemeId(nextLightId);
     setDarkUiThemeId(nextDarkId);
     setAccentMode(nextAccentMode);
-    setCustomAccent(nextAccent);
 
     const effective = nextTheme === 'system' ? getSystemPreference() : nextTheme;
     const tokens = getUiThemeById(effective, effective === 'dark' ? nextDarkId : nextLightId).tokens;
@@ -892,6 +943,7 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
       darkUiThemeId,
       accentMode,
       customAccent,
+      customAccentVersion: customAccentRecord.version,
     };
     // Capture previous snapshot before overwrite so we can notify only the
     // appearance fields that actually changed on this render.
@@ -913,7 +965,19 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
     localStorageAdapter.writeString(STORAGE_KEY_UI_THEME_LIGHT, lightUiThemeId);
     localStorageAdapter.writeString(STORAGE_KEY_UI_THEME_DARK, darkUiThemeId);
     localStorageAdapter.writeString(STORAGE_KEY_ACCENT_MODE, accentMode);
-    localStorageAdapter.writeString(STORAGE_KEY_COLOR, customAccent);
+    // Never let a stale effect overwrite a newer revision already on disk.
+    const storedAccent = parseCustomAccentRecord(
+      localStorageAdapter.readString(STORAGE_KEY_COLOR),
+    );
+    if (
+      shouldApplyCustomAccentRecord(storedAccent, customAccentRecord)
+      || storedAccent.version === customAccentRecord.version
+    ) {
+      localStorageAdapter.writeString(
+        STORAGE_KEY_COLOR,
+        serializeCustomAccentRecord(customAccentRecord),
+      );
+    }
     // Fix 1: Skip IPC broadcast on initial mount (values already match localStorage)
     if (!persistMountedRef.current) return;
     // Emit a keyed IPC notification for each changed appearance field so the
@@ -932,10 +996,21 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
     if (!previousAppearance || previousAppearance.accentMode !== accentMode) {
       notifySettingsChanged(STORAGE_KEY_ACCENT_MODE, accentMode);
     }
-    if (!previousAppearance || previousAppearance.customAccent !== customAccent) {
-      notifySettingsChanged(STORAGE_KEY_COLOR, customAccent);
+    if (
+      !previousAppearance
+      || previousAppearance.customAccent !== customAccent
+      || previousAppearance.customAccentVersion !== customAccentRecord.version
+    ) {
+      const decision = shouldBroadcastCustomAccentChange(
+        customAccentMutationSourceRef.current,
+        true,
+      );
+      customAccentMutationSourceRef.current = decision.nextSource;
+      if (decision.shouldBroadcast) {
+        notifySettingsChanged(STORAGE_KEY_COLOR, customAccentRecord);
+      }
     }
-  }, [theme, resolvedTheme, lightUiThemeId, darkUiThemeId, accentMode, customAccent, notifySettingsChanged]);
+  }, [theme, resolvedTheme, lightUiThemeId, darkUiThemeId, accentMode, customAccent, customAccentRecord, notifySettingsChanged]);
 
   // Listen for OS color scheme changes to keep systemPreference in sync
   useEffect(() => {
@@ -1035,6 +1110,7 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
   useSettingsStorageSync({
     enabled: enableSettingsSync,
     theme, lightUiThemeId, darkUiThemeId, accentMode, customAccent,
+    customAccentVersion: customAccentRecord.version,
     customCSS, uiFontFamilyId, hotkeyScheme, uiLanguage,
     terminalThemeId, followAppTerminalTheme, terminalFontFamilyId, terminalFontSize,
     sftpDoubleClickBehavior, sftpAutoSync, sftpShowHiddenFiles,
@@ -1042,7 +1118,8 @@ export const useSettingsState = (options: { enableSettingsSync?: boolean; enable
     showRecentHosts, hostClickBehavior, showOnlyUngroupedHostsInRoot, showSftpTab, showHostTreeSidebar, terminalSidePanelAutoOpen, terminalSidePanelAutoOpenTab, shellOnlyTabNumberShortcuts, disableTerminalFontZoom, restorePreviousSession, restoreTerminalCwd,
     editorWordWrap, sessionLogsEnabled, sessionLogsDir, sessionLogsFormat, sessionLogsTimestampsEnabled, sshDebugLogsEnabled, sshDeepLinkEnabled, jmsDeepLinkEnabled, explorerContextMenuEnabled,
     globalHotkeyEnabled, autoUpdateEnabled, windowOpacity, appIconVariant,
-    setTheme, setLightUiThemeId, setDarkUiThemeId, setAccentMode, setCustomAccent,
+    setTheme, setLightUiThemeId, setDarkUiThemeId, setAccentMode,
+    applyIncomingCustomAccent,
     setCustomCSS, setUiFontFamilyId, setHotkeyScheme, setUiLanguage,
     setTerminalThemeId, setTerminalThemeDarkId, setTerminalThemeLightId,
     setFollowAppTerminalThemeState, setTerminalFontFamilyId, setTerminalFontSize: applyIncomingTerminalFontSize,

application/syncPayload.ts

@@ -42,6 +42,10 @@ import {
   parseTerminalFontSizeRecord,
   serializeTerminalFontSizeRecord,
 } from './state/terminalFontSizeSync';
+import {
+  parseCustomAccentRecord,
+  serializeCustomAccentRecord,
+} from './state/customAccentSync';
 import {
   STORAGE_KEY_THEME,
   STORAGE_KEY_UI_THEME_LIGHT,
@@ -384,8 +388,8 @@ export function collectSyncableSettings(): SyncPayload['settings'] {
   if (darkUi) settings.darkUiThemeId = darkUi;
   const accentMode = localStorageAdapter.readString(STORAGE_KEY_ACCENT_MODE);
   if (accentMode === 'theme' || accentMode === 'custom') settings.accentMode = accentMode;
-  const accent = localStorageAdapter.readString(STORAGE_KEY_COLOR);
-  if (accent) settings.customAccent = accent;
+  const accentRaw = localStorageAdapter.readString(STORAGE_KEY_COLOR);
+  if (accentRaw) settings.customAccent = parseCustomAccentRecord(accentRaw).color;
   const uiFont = localStorageAdapter.readString(STORAGE_KEY_UI_FONT_FAMILY);
   if (uiFont) settings.uiFontFamilyId = uiFont;
   const lang = localStorageAdapter.readString(STORAGE_KEY_UI_LANGUAGE);
@@ -591,7 +595,17 @@ async function applySyncableSettings(settings: NonNullable<SyncPayload['settings
   if (settings.lightUiThemeId != null) localStorageAdapter.writeString(STORAGE_KEY_UI_THEME_LIGHT, settings.lightUiThemeId);
   if (settings.darkUiThemeId != null) localStorageAdapter.writeString(STORAGE_KEY_UI_THEME_DARK, settings.darkUiThemeId);
   if (settings.accentMode != null) localStorageAdapter.writeString(STORAGE_KEY_ACCENT_MODE, settings.accentMode);
-  if (settings.customAccent != null) localStorageAdapter.writeString(STORAGE_KEY_COLOR, settings.customAccent);
+  if (settings.customAccent != null) {
+    const existing = parseCustomAccentRecord(localStorageAdapter.readString(STORAGE_KEY_COLOR));
+    localStorageAdapter.writeString(
+      STORAGE_KEY_COLOR,
+      serializeCustomAccentRecord({
+        color: parseCustomAccentRecord(settings.customAccent).color,
+        // Bump so peer windows' version gates accept the synced value.
+        version: Math.max(existing.version, 0) + 1,
+      }),
+    );
+  }
   if (settings.uiFontFamilyId != null) localStorageAdapter.writeString(STORAGE_KEY_UI_FONT_FAMILY, settings.uiFontFamilyId);
   if (settings.uiLanguage != null) localStorageAdapter.writeString(STORAGE_KEY_UI_LANGUAGE, settings.uiLanguage);
   if (settings.customCSS != null) localStorageAdapter.writeString(STORAGE_KEY_CUSTOM_CSS, settings.customCSS);