@vellumai/assistant 0.11.4-staging.2 → 0.11.4-staging.4

package/src/cli/commands/domain.ts

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import { resolveBundledCliModule } from "../bundled-modules.js";
 import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { getCliLogger } from "../logger.js";
@@ -19,9 +20,11 @@ const log = getCliLogger("domain");
  * synchronously, so there is no place to await a module load.
  */
 function envDomains(): { apexDomain: string; baseDomain: string } {
-  const { getApexDomain, getAssistantDomain } = loadModule(
-    "../../config/env.js",
-  ) as typeof import("../../config/env.js");
+  const { getApexDomain, getAssistantDomain } = resolveBundledCliModule(
+    "configEnv",
+    () =>
+      loadModule("../../config/env.js") as typeof import("../../config/env.js"),
+  );
   return { apexDomain: getApexDomain(), baseDomain: getAssistantDomain() };
 }
 

package/src/cli/commands/email.ts

@@ -16,6 +16,7 @@ import {
 } from "../../ipc/cli-client.js";
 import { guessMimeType } from "../../util/mime-type.js";
 import { readStdinSync } from "../../util/read-stdin.js";
+import { resolveBundledCliModule } from "../bundled-modules.js";
 import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { getCliLogger } from "../logger.js";
@@ -60,9 +61,11 @@ function handleEmailIpcError(
  * synchronously, so there is no place to await a module load.
  */
 function assistantDomain(): string {
-  const { getAssistantDomain } = loadModule(
-    "../../config/env.js",
-  ) as typeof import("../../config/env.js");
+  const { getAssistantDomain } = resolveBundledCliModule(
+    "configEnv",
+    () =>
+      loadModule("../../config/env.js") as typeof import("../../config/env.js"),
+  );
   return getAssistantDomain();
 }
 

package/src/cli/commands/keys.ts

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 
 import type { Command } from "commander";
 
+import { resolveBundledCliModule } from "../bundled-modules.js";
 import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
@@ -16,9 +17,13 @@ const loadModule = createRequire(import.meta.url);
  * callbacks synchronously, so there is no place to await a module load.
  */
 function apiKeyProviders(): readonly string[] {
-  const { API_KEY_PROVIDERS } = loadModule(
-    "../../providers/provider-secret-catalog.js",
-  ) as typeof import("../../providers/provider-secret-catalog.js");
+  const { API_KEY_PROVIDERS } = resolveBundledCliModule(
+    "providerSecretCatalog",
+    () =>
+      loadModule(
+        "../../providers/provider-secret-catalog.js",
+      ) as typeof import("../../providers/provider-secret-catalog.js"),
+  );
   return API_KEY_PROVIDERS;
 }
 

package/src/cli/commands/plugins.ts

@@ -15,6 +15,7 @@ import { cliIpcCall } from "../../ipc/cli-client.js";
 import { stripAnsiAndControlChars } from "../../util/ansi.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import { truncate } from "../../util/truncate.js";
+import { resolveBundledCliModule } from "../bundled-modules.js";
 import { yellow } from "../lib/cli-colors.js";
 import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
@@ -61,64 +62,112 @@ const loadModule = createRequire(import.meta.url);
 /** Lazy accessors: each getter loads its implementation module on first use. */
 const libs = {
   get catalogCache() {
-    return loadModule(
-      "../lib/plugin-catalog-cache.js",
-    ) as typeof import("../lib/plugin-catalog-cache.js");
+    return resolveBundledCliModule(
+      "pluginCatalogCache",
+      () =>
+        loadModule(
+          "../lib/plugin-catalog-cache.js",
+        ) as typeof import("../lib/plugin-catalog-cache.js"),
+    );
   },
   get catalogLocal() {
-    return loadModule(
-      "../lib/plugin-catalog-local.js",
-    ) as typeof import("../lib/plugin-catalog-local.js");
+    return resolveBundledCliModule(
+      "pluginCatalogLocal",
+      () =>
+        loadModule(
+          "../lib/plugin-catalog-local.js",
+        ) as typeof import("../lib/plugin-catalog-local.js"),
+    );
   },
   get diff() {
-    return loadModule(
-      "../lib/diff-plugin.js",
-    ) as typeof import("../lib/diff-plugin.js");
+    return resolveBundledCliModule(
+      "pluginDiff",
+      () =>
+        loadModule(
+          "../lib/diff-plugin.js",
+        ) as typeof import("../lib/diff-plugin.js"),
+    );
   },
   get inspect() {
-    return loadModule(
-      "../lib/inspect-plugin.js",
-    ) as typeof import("../lib/inspect-plugin.js");
+    return resolveBundledCliModule(
+      "pluginInspect",
+      () =>
+        loadModule(
+          "../lib/inspect-plugin.js",
+        ) as typeof import("../lib/inspect-plugin.js"),
+    );
   },
   get installGitHub() {
-    return loadModule(
-      "../lib/install-from-github.js",
-    ) as typeof import("../lib/install-from-github.js");
+    return resolveBundledCliModule(
+      "pluginInstallGitHub",
+      () =>
+        loadModule(
+          "../lib/install-from-github.js",
+        ) as typeof import("../lib/install-from-github.js"),
+    );
   },
   get installPlatform() {
-    return loadModule(
-      "../lib/install-from-platform.js",
-    ) as typeof import("../lib/install-from-platform.js");
+    return resolveBundledCliModule(
+      "pluginInstallPlatform",
+      () =>
+        loadModule(
+          "../lib/install-from-platform.js",
+        ) as typeof import("../lib/install-from-platform.js"),
+    );
   },
   get installed() {
-    return loadModule(
-      "../lib/list-installed-plugins.js",
-    ) as typeof import("../lib/list-installed-plugins.js");
+    return resolveBundledCliModule(
+      "pluginInstalled",
+      () =>
+        loadModule(
+          "../lib/list-installed-plugins.js",
+        ) as typeof import("../lib/list-installed-plugins.js"),
+    );
   },
   get pinHistory() {
-    return loadModule(
-      "../lib/plugin-pin-history.js",
-    ) as typeof import("../lib/plugin-pin-history.js");
+    return resolveBundledCliModule(
+      "pluginPinHistory",
+      () =>
+        loadModule(
+          "../lib/plugin-pin-history.js",
+        ) as typeof import("../lib/plugin-pin-history.js"),
+    );
   },
   get search() {
-    return loadModule(
-      "../lib/search-plugins.js",
-    ) as typeof import("../lib/search-plugins.js");
+    return resolveBundledCliModule(
+      "pluginSearch",
+      () =>
+        loadModule(
+          "../lib/search-plugins.js",
+        ) as typeof import("../lib/search-plugins.js"),
+    );
   },
   get surfaces() {
-    return loadModule(
-      "../lib/plugin-surfaces.js",
-    ) as typeof import("../lib/plugin-surfaces.js");
+    return resolveBundledCliModule(
+      "pluginSurfaces",
+      () =>
+        loadModule(
+          "../lib/plugin-surfaces.js",
+        ) as typeof import("../lib/plugin-surfaces.js"),
+    );
   },
   get uninstall() {
-    return loadModule(
-      "../lib/uninstall-plugin.js",
-    ) as typeof import("../lib/uninstall-plugin.js");
+    return resolveBundledCliModule(
+      "pluginUninstall",
+      () =>
+        loadModule(
+          "../lib/uninstall-plugin.js",
+        ) as typeof import("../lib/uninstall-plugin.js"),
+    );
   },
   get upgrade() {
-    return loadModule(
-      "../lib/upgrade-plugin.js",
-    ) as typeof import("../lib/upgrade-plugin.js");
+    return resolveBundledCliModule(
+      "pluginUpgrade",
+      () =>
+        loadModule(
+          "../lib/upgrade-plugin.js",
+        ) as typeof import("../lib/upgrade-plugin.js"),
+    );
   },
 };
 

package/src/cli/commands/schedules.ts

@@ -39,9 +39,39 @@ interface ScheduleRecord {
   wakeConversationId: string | null;
   sourceKey: string | null;
   userEnabled: boolean | null;
+  disarmReason: string | null;
   isOneShot: boolean;
 }
 
+/** Plain-language copy for each `disarmReason` the daemon sends. */
+const DISARM_REASON_TEXT: Record<string, string> = {
+  user_disabled: "turned off by you",
+  plugin_removed: "plugin removed",
+  plugin_disabled: "plugin disabled",
+  declaration_removed: "removed from plugin",
+  declaration_disabled: "paused by plugin",
+};
+
+/**
+ * Why a schedule is off, when the daemon knows. An off row with no reason (an
+ * imperative schedule, or a plugin row from a daemon that predates the field)
+ * reads as plain "disabled".
+ */
+function describeDisarmReason(schedule: ScheduleRecord): string | null {
+  if (schedule.enabled || !schedule.disarmReason) {
+    return null;
+  }
+  return DISARM_REASON_TEXT[schedule.disarmReason] ?? null;
+}
+
+function formatEnabledCell(schedule: ScheduleRecord): string {
+  if (schedule.enabled) {
+    return "enabled";
+  }
+  const reason = describeDisarmReason(schedule);
+  return reason ? `off (${reason})` : "disabled";
+}
+
 interface ListSchedulesResponse {
   schedules: ScheduleRecord[];
 }
@@ -116,7 +146,7 @@ export function registerSchedulesCommand(program: Command): void {
           const rows = entries.map((schedule) => ({
             id: schedule.id,
             name: schedule.name,
-            enabled: schedule.enabled ? "enabled" : "disabled",
+            enabled: formatEnabledCell(schedule),
             mode: schedule.mode,
             source: describeScheduleSource(schedule.sourceKey) ?? "",
             schedule: describeSchedule(schedule),
@@ -247,6 +277,10 @@ export function registerSchedulesCommand(program: Command): void {
             ["Source conversation", schedule.createdFromConversationId ?? "—"],
             ["Plugin", describeScheduleSource(schedule.sourceKey) ?? "-"],
           ];
+          const disarmReason = describeDisarmReason(schedule);
+          if (disarmReason) {
+            fields.push(["Paused", disarmReason]);
+          }
           const labelWidth = Math.max(...fields.map(([label]) => label.length));
           for (const [label, value] of fields) {
             log.info(`${`${label}:`.padEnd(labelWidth + 2)}${value}`);

package/src/cli/lib/bundled-marketplace.json

@@ -232,7 +232,7 @@
       "source": {
         "source": "github",
         "repo": "vellum-ai/level-up",
-        "ref": "d3cbb50f8aba1f8320cd2d59ea3a85d0a4e9210b"
+        "ref": "4357028acc339c6d6f718d5d6ab279ebf198673b"
       },
       "description": "Surfaces a first-class \"Level Up\" diff card whenever the assistant edits its own skills or plugins, so you can see how it improved itself after the fact.",
       "category": "developer",

package/src/config/__tests__/balanced-model-experiment.test.ts

@@ -0,0 +1,278 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import type { z } from "zod";
+
+import { setOverridesForTesting } from "../../__tests__/feature-flag-test-helpers.js";
+import {
+  catalogMaxOutputTokens,
+  isModelInCatalog,
+} from "../../providers/model-catalog.js";
+import { getManagedUpstream } from "../../providers/vellum-model-routing.js";
+import { BALANCED_MODEL_EXPERIMENT_FLAG_KEY } from "../balanced-model-experiment.js";
+import {
+  CODE_DEFAULT_PROFILE_ENTRIES,
+  getEffectiveProfilesForProvider,
+  resolveDefaultProfileForProvider,
+} from "../default-profile-catalog.js";
+import { clearCachedOverrides } from "../feature-flag-cache.js";
+import { resolveCallSiteConfig } from "../llm-resolver.js";
+import {
+  type DefaultProviderConfig,
+  LLMSchema,
+  type ProfileEntry,
+} from "../schemas/llm.js";
+
+// The `experiment-balanced-model-2026-08-06` arm repoints the model the managed
+// Balanced profile resolves to. Both the runtime resolver and the client-facing
+// profile listing go through `defaultProfileBodyForProvider`, so both are
+// exercised here: a disagreement between them shows the user one model beside a
+// profile that runs another.
+
+const FLAG = BALANCED_MODEL_EXPERIMENT_FLAG_KEY;
+const SHIPPED_MODEL = "gpt-5.6-luna";
+const GLM_MODEL = "accounts/fireworks/models/glm-5p2";
+
+function setArm(value: boolean | string): void {
+  setOverridesForTesting({ [FLAG]: value });
+}
+
+const managed: DefaultProviderConfig = { provider: "vellum" };
+
+function llmWithActiveBalanced(
+  overrides: Record<string, unknown> = {},
+): z.infer<typeof LLMSchema> {
+  return LLMSchema.parse({
+    profiles: {},
+    profileOrder: [],
+    activeProfile: "balanced",
+    defaultProvider: managed,
+    ...overrides,
+  });
+}
+
+afterEach(() => {
+  clearCachedOverrides();
+});
+
+describe("balanced-model experiment arms", () => {
+  test("terra repoints mainAgent at gpt-5.6-terra on the managed connection", () => {
+    setArm("terra");
+    const resolved = resolveCallSiteConfig(
+      "mainAgent",
+      llmWithActiveBalanced(),
+    );
+    expect(resolved.model).toBe("gpt-5.6-terra");
+    expect(resolved.provider).toBe("vellum");
+    expect(getManagedUpstream("gpt-5.6-terra")).toBe("openai");
+
+    const entry = resolveDefaultProfileForProvider(
+      undefined,
+      "balanced",
+      managed,
+    );
+    expect(entry?.model).toBe("gpt-5.6-terra");
+    expect(entry?.provider).toBe("vellum");
+    // Routing-identity providers derive their connection per request.
+    expect(entry?.provider_connection).toBeUndefined();
+    expect(entry?.source).toBe("managed");
+  });
+
+  test("glm-5p2 repoints mainAgent at GLM 5.2 within the model's output cap", () => {
+    setArm("glm-5p2");
+    const resolved = resolveCallSiteConfig(
+      "mainAgent",
+      llmWithActiveBalanced(),
+    );
+    expect(resolved.model).toBe(GLM_MODEL);
+    expect(resolved.provider).toBe("vellum");
+
+    const upstream = getManagedUpstream(GLM_MODEL);
+    expect(upstream).toBe("fireworks");
+    const cap = catalogMaxOutputTokens(upstream as string, GLM_MODEL);
+    expect(cap).toBeDefined();
+    expect(resolved.maxTokens).toBeLessThanOrEqual(cap as number);
+    // Only the model moves: the shipped token budget stands.
+    expect(resolved.maxTokens).toBe(
+      CODE_DEFAULT_PROFILE_ENTRIES.balanced.maxTokens as number,
+    );
+  });
+
+  test("an arm changes only the model of the managed balanced body", () => {
+    setArm("terra");
+    const entry = resolveDefaultProfileForProvider(
+      undefined,
+      "balanced",
+      managed,
+    );
+    const shipped = CODE_DEFAULT_PROFILE_ENTRIES.balanced;
+    expect(entry).toEqual({ ...shipped, model: "gpt-5.6-terra" });
+  });
+
+  test("the other default profiles are untouched by an arm", () => {
+    setArm("glm-5p2");
+    for (const key of [
+      "quality-optimized",
+      "cost-optimized",
+      "latency-optimized",
+    ]) {
+      expect(
+        resolveDefaultProfileForProvider(undefined, key, managed)?.model,
+      ).toBe(CODE_DEFAULT_PROFILE_ENTRIES[key].model);
+    }
+  });
+
+  test("every pinned arm model is managed-routable and in its upstream catalog", () => {
+    for (const model of ["gpt-5.6-terra", GLM_MODEL]) {
+      const upstream = getManagedUpstream(model);
+      expect(upstream).not.toBeNull();
+      expect(isModelInCatalog(upstream as string, model)).toBe(true);
+    }
+  });
+});
+
+describe("balanced-model experiment fallbacks", () => {
+  const shippedCases: [string, () => void][] = [
+    ["the flag is unset", () => clearCachedOverrides()],
+    ["no override is present", () => setOverridesForTesting({})],
+    ["the arm is control", () => setArm("control")],
+    ["the arm is an unknown string", () => setArm("gpt-9-does-not-exist")],
+    ["the arm is the empty string", () => setArm("")],
+    ["the value is boolean true", () => setArm(true)],
+    ["the value is boolean false", () => setArm(false)],
+    // The arm is remote input, so it can name an Object.prototype member. The
+    // pin table is a Map, which has no such members to inherit.
+    ["the arm is constructor", () => setArm("constructor")],
+    ["the arm is toString", () => setArm("toString")],
+    ["the arm is valueOf", () => setArm("valueOf")],
+    ["the arm is __proto__", () => setArm("__proto__")],
+    ["the arm is hasOwnProperty", () => setArm("hasOwnProperty")],
+  ];
+
+  for (const [label, seed] of shippedCases) {
+    test(`balanced stays on the shipped model when ${label}`, () => {
+      seed();
+      expect(
+        resolveDefaultProfileForProvider(undefined, "balanced", managed)?.model,
+      ).toBe(SHIPPED_MODEL);
+      expect(
+        resolveCallSiteConfig("mainAgent", llmWithActiveBalanced()).model,
+      ).toBe(SHIPPED_MODEL);
+    });
+  }
+
+  test("the shipped catalog body is the control arm", () => {
+    expect(CODE_DEFAULT_PROFILE_ENTRIES.balanced.model).toBe(SHIPPED_MODEL);
+  });
+
+  test("the registry default is control, which the override-only flag read assumes", () => {
+    const registryPath = join(
+      import.meta.dirname,
+      "..",
+      "..",
+      "..",
+      "..",
+      "meta",
+      "feature-flags",
+      "feature-flag-registry.json",
+    );
+    const registry = JSON.parse(readFileSync(registryPath, "utf-8")) as {
+      flags: {
+        key: string;
+        scope: string;
+        defaultEnabled: boolean | string;
+        values?: string[];
+      }[];
+    };
+    const flag = registry.flags.find((entry) => entry.key === FLAG);
+    expect(flag).toBeDefined();
+    expect(flag?.scope).toBe("assistant");
+    expect(flag?.defaultEnabled).toBe("control");
+    expect(flag?.values).toEqual(["control", "terra", "glm-5p2"]);
+  });
+});
+
+describe("balanced-model experiment boundaries", () => {
+  test("a user-owned balanced shadow wins over the arm", () => {
+    setArm("terra");
+    const profiles: Record<string, ProfileEntry> = {
+      balanced: { source: "user", provider: "openai", model: "gpt-5.5" },
+    };
+    expect(
+      resolveDefaultProfileForProvider(profiles, "balanced", managed),
+    ).toEqual(profiles.balanced);
+    expect(
+      resolveCallSiteConfig("mainAgent", llmWithActiveBalanced({ profiles }))
+        .model,
+    ).toBe("gpt-5.5");
+  });
+
+  test("a managed-source stub still resolves to the arm's body", () => {
+    setArm("terra");
+    const profiles: Record<string, ProfileEntry> = {
+      balanced: { source: "managed", label: "My Balanced" },
+    };
+    const entry = resolveDefaultProfileForProvider(
+      profiles,
+      "balanced",
+      managed,
+    );
+    expect(entry?.model).toBe("gpt-5.6-terra");
+    expect(entry?.label).toBe("My Balanced");
+  });
+
+  test("the chatgpt and BYOK columns stay out of the experiment", () => {
+    setArm("terra");
+    for (const provider of ["anthropic", "openai", "chatgpt"] as const) {
+      const armed = resolveDefaultProfileForProvider(undefined, "balanced", {
+        provider,
+      });
+      clearCachedOverrides();
+      const shipped = resolveDefaultProfileForProvider(undefined, "balanced", {
+        provider,
+      });
+      expect(armed).toEqual(shipped as ProfileEntry);
+      expect(armed?.provider).toBe(provider);
+      setArm("terra");
+    }
+  });
+
+  test("an install with no defaultProvider still picks up the arm", () => {
+    setArm("glm-5p2");
+    expect(
+      resolveDefaultProfileForProvider(undefined, "balanced", null)?.model,
+    ).toBe(GLM_MODEL);
+  });
+});
+
+describe("client-facing profile listing", () => {
+  test("reports the arm's model so the UI matches what runs", () => {
+    setArm("terra");
+    const profiles = getEffectiveProfilesForProvider(undefined, managed);
+    expect(profiles.balanced?.model).toBe("gpt-5.6-terra");
+    expect(profiles["quality-optimized"]?.model).toBe(
+      CODE_DEFAULT_PROFILE_ENTRIES["quality-optimized"].model,
+    );
+  });
+
+  test("reports the shipped model on the control arm", () => {
+    setArm("control");
+    expect(
+      getEffectiveProfilesForProvider(undefined, managed).balanced?.model,
+    ).toBe(SHIPPED_MODEL);
+  });
+
+  test("agrees with the runtime resolver on every arm", () => {
+    for (const arm of ["control", "terra", "glm-5p2", "nonsense"]) {
+      setArm(arm);
+      const listed = getEffectiveProfilesForProvider(undefined, managed)
+        .balanced?.model;
+      const resolved = resolveCallSiteConfig(
+        "mainAgent",
+        llmWithActiveBalanced(),
+      ).model;
+      expect(listed).toBe(resolved as string);
+    }
+  });
+});

package/src/config/assistant-feature-flags.ts

@@ -59,6 +59,12 @@ function loadDefaultsRegistry(): FeatureFlagDefaultsRegistry {
     // Works in Docker / packaged builds where the repo-root `meta/` dir
     // is not available.
     join(thisDir, REGISTRY_FILENAME),
+    ...(process.platform === "win32"
+      ? [
+          // Packaged Windows CLI runtime: assets live beside the executable.
+          join(dirname(process.execPath), REGISTRY_FILENAME),
+        ]
+      : []),
     // Packaged macOS app layout: the daemon binary lives at
     // <App>.app/Contents/MacOS/vellum-daemon and the registry is copied
     // to <App>.app/Contents/Resources/ by build.sh. In bun --compile
@@ -190,11 +196,11 @@ const DEFAULT_INIT_RETRY_BACKOFFS_MS: readonly number[] = [
  * intentionally simulate an unreachable gateway and want immediate
  * fallback without waiting through the production schedule).
  *
- * No-ops when the cache is already populated — callers that want to
- * refresh must call `clearFeatureFlagOverridesCache()` first. This lets
- * tests preseed flag state via `setOverridesForTesting()` (in
- * `__tests__/feature-flag-test-helpers.ts`) without the gateway IPC call
- * clobbering their setup.
+ * No-ops when the cache is already populated — this is the load-time
+ * populate, and `refreshOverridesFromGateway()` is what re-reads a cache that
+ * already holds values. The no-op also lets tests preseed flag state via
+ * `setOverridesForTesting()` (in `__tests__/feature-flag-test-helpers.ts`)
+ * without the gateway IPC call clobbering their setup.
  *
  * Resolves `true` when the override cache is populated from the gateway and
  * `false` when the cache is left unset (exhausted retries / unreachable
@@ -274,10 +280,13 @@ function loadOverrides(): Record<string, boolean | string> {
  * Invalidate the cached overrides so the next call to
  * `isAssistantFeatureFlagEnabled` re-reads from the gateway.
  *
- * Called by `refreshOverridesFromGateway()` when the gateway pushes a
- * `feature_flags_changed` event, and by tests between cases to reset
- * module state. (Tests typically call `setOverridesForTesting()` from
- * `__tests__/feature-flag-test-helpers.ts`, which combines clear + seed.)
+ * Used by tests between cases to reset module state. (Tests typically call
+ * `setOverridesForTesting()` from `__tests__/feature-flag-test-helpers.ts`,
+ * which combines clear + seed.)
+ *
+ * Not a step in refreshing from the gateway: `refreshOverridesFromGateway()`
+ * swaps the cache atomically so flag values never read as unset while a
+ * refresh is in flight.
  */
 export function clearFeatureFlagOverridesCache(): void {
   clearCachedOverrides();
@@ -286,18 +295,30 @@ export function clearFeatureFlagOverridesCache(): void {
 /**
  * Re-fetch feature flag overrides from the gateway.
  *
- * Clears the cached overrides and re-runs the gateway IPC fetch without
- * retries (the gateway is known to be up because it just pushed an event).
- * Called by the gateway flag listener when a `feature_flags_changed` event
- * arrives.
+ * Runs the gateway IPC fetch without retries (the gateway is known to be up
+ * because it just pushed an event) and replaces the cache only once that fetch
+ * succeeds. Called by the gateway flag listener when a `feature_flags_changed`
+ * event arrives and on reconnect.
+ *
+ * The swap is atomic on purpose. The previously fetched values stay readable
+ * for the whole call, so a sync flag read that lands mid-refresh sees the last
+ * known values rather than an empty cache, and a failed fetch leaves them in
+ * place rather than dropping every flag to its registry default until the next
+ * event. A flag that selects behavior rather than gating it (an experiment
+ * arm, a kill switch) therefore cannot flip to its default because one IPC
+ * call timed out.
  *
  * Resolves `true` when the cache was repopulated from the gateway, `false`
  * when the fetch came back empty/failed — callers gate persisted-state
  * reconciliation on a `true` result.
  */
 export async function refreshOverridesFromGateway(): Promise<boolean> {
-  clearFeatureFlagOverridesCache();
-  return initFeatureFlagOverrides({ retryBackoffsMs: [] });
+  const gatewayOverrides = await fetchOverridesFromGateway();
+  if (Object.keys(gatewayOverrides).length === 0) {
+    return false;
+  }
+  setCachedOverrides(gatewayOverrides, { fromGateway: true });
+  return true;
 }
 
 // ---------------------------------------------------------------------------