@vellumai/assistant 0.9.1-staging.1 → 0.10.0-staging.2

package/src/cli/lib/upgrade-plugin.ts

@@ -16,11 +16,11 @@
  * re-install at the current pin — the underlying
  * {@link ./install-from-github.installPlugin} performs that atomically, and the
  * previously installed copy (including any local edits) is replaced wholesale.
- * `ours`/`theirs` instead three-way merge the on-disk tree and the pin against
- * the re-materialized install commit so non-conflicting local edits survive,
- * resolving conflicting hunks toward the local edit or the pin respectively.
- * `assistant` is reserved for assistant-driven conflict resolution and is not
- * yet implemented.
+ * `ours`/`theirs`/`assistant` instead three-way merge the on-disk tree and the
+ * pin against the re-materialized install commit so non-conflicting local edits
+ * survive; conflicting hunks resolve toward the local edit (`ours`) or the pin
+ * (`theirs`), while `assistant` writes git conflict markers into the file and
+ * reports the conflicted paths for the assistant to resolve.
  *
  * Designed for direct programmatic use with injected dependencies, mirroring
  * the sibling plugin libraries. The CLI command `assistant plugins upgrade
@@ -55,7 +55,7 @@ import {
   readInstallMeta,
   sanitizePluginName,
 } from "./install-from-github.js";
-import { mergePluginTree } from "./merge-plugin-tree.js";
+import { type ConflictLabels, mergePluginTree } from "./merge-plugin-tree.js";
 import { computeFingerprint, fingerprintsEqual } from "./plugin-fingerprint.js";
 import { PluginNotInstalledError } from "./uninstall-plugin.js";
 
@@ -67,8 +67,8 @@ import { PluginNotInstalledError } from "./uninstall-plugin.js";
  *   wholesale. Matches the historical upgrade behavior.
  * - `ours` — three-way merge; conflicting hunks resolve toward the local edit.
  * - `theirs` — three-way merge; conflicting hunks resolve toward the pin.
- * - `assistant` — hand conflicts to the assistant to resolve (not yet
- *   implemented).
+ * - `assistant` — three-way merge that writes git conflict markers into
+ *   conflicting files and reports them for the assistant to resolve.
  */
 export type PluginUpgradeStrategy =
   | "ours"
@@ -151,6 +151,19 @@ export interface PluginUpgradeResult {
   readonly dryRun: boolean;
   /** Conflict-resolution strategy the upgrade applied. */
   readonly strategy: PluginUpgradeStrategy;
+  /**
+   * Paths (relative to {@link PluginUpgradeResult.target}) left for the
+   * assistant to resolve under the `assistant` strategy: text files carry git
+   * conflict markers, modify/delete divergences keep the surviving content.
+   * Always empty for other strategies.
+   */
+  readonly conflicts: readonly string[];
+  /**
+   * Paths of binary files that conflicted under the `assistant` strategy; the
+   * local copy was kept since markers cannot be written into binary content.
+   * Always empty for other strategies.
+   */
+  readonly binaryConflicts: readonly string[];
   /**
    * Whether the installed copy lacked resolvable provenance before the
    * upgrade. Such installs are re-pinned to the current SHA, which also
@@ -170,16 +183,6 @@ export class PluginNotUpgradableError extends Error {
   }
 }
 
-/** A requested merge strategy is recognized but not yet implemented. */
-export class PluginUpgradeStrategyUnsupportedError extends Error {
-  constructor(readonly strategy: PluginUpgradeStrategy) {
-    super(
-      `Upgrade strategy "${strategy}" is not yet supported. Use one of: ours, theirs, overwrite.`,
-    );
-    this.name = "PluginUpgradeStrategyUnsupportedError";
-  }
-}
-
 /**
  * A merge strategy (`ours`/`theirs`) was requested but the install-time
  * baseline needed for a three-way merge cannot be reconstructed.
@@ -205,16 +208,16 @@ function pluginTarget(name: string, deps: UpgradePluginDeps): string {
  * Move an installed plugin to the marketplace's current pin.
  *
  * The `strategy` controls how local edits are reconciled with the pin:
- * `overwrite` (default) re-installs the pin wholesale; `ours`/`theirs` do a
- * three-way merge that carries non-conflicting local edits forward, resolving
- * conflicting hunks toward the local edit or the pin respectively; `assistant`
- * is not yet implemented.
+ * `overwrite` (default) re-installs the pin wholesale; `ours`/`theirs`/
+ * `assistant` do a three-way merge that carries non-conflicting local edits
+ * forward, resolving conflicting hunks toward the local edit (`ours`) or the
+ * pin (`theirs`), or leaving git conflict markers in the file for the assistant
+ * to resolve (`assistant`).
  *
  * Throws {@link PluginNotInstalledError} when no copy is installed,
  * {@link PluginNotUpgradableError} when the install has no marketplace entry to
- * advance to, {@link PluginUpgradeStrategyUnsupportedError} for the `assistant`
- * strategy, {@link PluginMergeBaselineError} when a merge strategy is requested
- * but the install-time baseline cannot be reconstructed,
+ * advance to, {@link PluginMergeBaselineError} when a merge strategy is
+ * requested but the install-time baseline cannot be reconstructed,
  * {@link PluginSourceUnavailableError} when the marketplace catalog is
  * temporarily unreachable (a retryable outage, distinct from the permanent
  * no-entry case), and propagates {@link installPlugin}'s errors (e.g. source
@@ -228,10 +231,6 @@ export async function upgradePlugin(
   const dryRun = opts.dryRun ?? false;
   const strategy = opts.strategy ?? DEFAULT_PLUGIN_UPGRADE_STRATEGY;
 
-  if (strategy === "assistant") {
-    throw new PluginUpgradeStrategyUnsupportedError(strategy);
-  }
-
   let inspection: PluginInspection;
   try {
     inspection = await inspectPlugin(
@@ -292,6 +291,8 @@ export async function upgradePlugin(
       fileCount: null,
       dryRun,
       strategy,
+      conflicts: [],
+      binaryConflicts: [],
       provenanceWasUnknown: false,
     };
   }
@@ -308,13 +309,20 @@ export async function upgradePlugin(
       fileCount: null,
       dryRun: true,
       strategy,
+      conflicts: [],
+      binaryConflicts: [],
       provenanceWasUnknown,
     };
   }
 
-  // `ours`/`theirs` carry local edits forward via a three-way merge; the
-  // default `overwrite` discards them and re-installs the pin wholesale.
-  if (strategy === "ours" || strategy === "theirs") {
+  // `ours`/`theirs`/`assistant` carry local edits forward via a three-way
+  // merge; the default `overwrite` discards them and re-installs the pin
+  // wholesale.
+  if (
+    strategy === "ours" ||
+    strategy === "theirs" ||
+    strategy === "assistant"
+  ) {
     return mergeUpgrade(
       {
         name,
@@ -323,6 +331,8 @@ export async function upgradePlugin(
         remote,
         fromCommit,
         fromTimestamp,
+        toCommit,
+        toTimestamp,
         provenanceWasUnknown,
       },
       deps,
@@ -350,6 +360,8 @@ export async function upgradePlugin(
     fileCount: result.fileCount,
     dryRun: false,
     strategy,
+    conflicts: [],
+    binaryConflicts: [],
     provenanceWasUnknown,
   };
 }
@@ -359,22 +371,35 @@ export async function upgradePlugin(
  * and the marketplace pin (`theirs`) against the re-materialized install commit
  * (`base`), then atomically swapping the merged tree into place pinned at the
  * new commit. Conflicting hunks resolve toward `ours` or `theirs` per the
- * strategy; non-conflicting edits from both sides survive.
+ * strategy, or are left as git conflict markers under `assistant`;
+ * non-conflicting edits from both sides survive.
  */
 async function mergeUpgrade(
   ctx: {
     readonly name: string;
-    readonly strategy: "ours" | "theirs";
+    readonly strategy: "ours" | "theirs" | "assistant";
     readonly local: PluginLocalInfo;
     readonly remote: PluginRemoteInfo;
     readonly fromCommit: string | null;
     readonly fromTimestamp: string | null;
+    readonly toCommit: string;
+    readonly toTimestamp: string | null;
     readonly provenanceWasUnknown: boolean;
   },
   deps: UpgradePluginDeps,
 ): Promise<PluginUpgradeResult> {
   const { name, strategy, local, remote } = ctx;
 
+  // Marker labels name each side by its commit so the assistant can tell the
+  // local edit from the incoming pin when resolving.
+  const shortSha = (sha: string | null): string =>
+    sha ? sha.slice(0, 7) : "unknown";
+  const conflictLabels: ConflictLabels = {
+    ours: `local edits (was ${shortSha(ctx.fromCommit)})`,
+    base: `install baseline ${shortSha(ctx.fromCommit)}`,
+    theirs: `upgrade pin ${shortSha(ctx.toCommit)}`,
+  };
+
   const meta = readInstallMeta(local.target);
   if (!meta || !meta.commit || !meta.fingerprint) {
     throw new PluginMergeBaselineError(
@@ -461,12 +486,13 @@ async function mergeUpgrade(
       );
     }
 
-    const fileCount = await mergePluginTree({
+    const merge = await mergePluginTree({
       baseDir,
       oursDir: local.target,
       theirsDir,
       destDir: stagingDir,
       strategy,
+      conflictLabels,
     });
 
     const toCommit = theirs.commit ?? remote.commit;
@@ -488,9 +514,11 @@ async function mergeUpgrade(
       toCommit,
       toTimestamp,
       target: join(pluginsDir, name),
-      fileCount,
+      fileCount: merge.fileCount,
       dryRun: false,
       strategy,
+      conflicts: merge.conflicts,
+      binaryConflicts: merge.binaryConflicts,
       provenanceWasUnknown: ctx.provenanceWasUnknown,
     };
   } catch (err) {

package/src/cli/program.ts

@@ -34,8 +34,7 @@ import { registerImageGenerationCommand } from "./commands/image-generation.js";
 import { registerInferenceCommand } from "./commands/inference.js";
 import { registerKeysCommand } from "./commands/keys.js";
 import { registerMcpCommand } from "./commands/mcp.js";
-import { registerMemoryV2Command } from "./commands/memory-v2.js";
-import { registerMemoryV3Command } from "./commands/memory-v3.js";
+import { registerMemoryCommand } from "./commands/memory/index.js";
 import { registerNotificationsCommand } from "./commands/notifications.js";
 import { registerOAuthCommand } from "./commands/oauth/index.js";
 import { registerPendingCommand } from "./commands/pending.js";
@@ -130,8 +129,7 @@ Examples:
   registerInferenceCommand(program);
   registerKeysCommand(program);
   registerMcpCommand(program);
-  registerMemoryV2Command(program);
-  registerMemoryV3Command(program);
+  registerMemoryCommand(program);
   registerNotificationsCommand(program);
   registerOAuthCommand(program);
   registerPendingCommand(program);

package/src/config/__tests__/sync-gated-profiles.test.ts

@@ -0,0 +1,368 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+const WORKSPACE_DIR = process.env.VELLUM_WORKSPACE_DIR!;
+const CONFIG_PATH = join(WORKSPACE_DIR, "config.json");
+
+function ensureTestDir(): void {
+  const dirs = [
+    WORKSPACE_DIR,
+    join(WORKSPACE_DIR, "data"),
+    join(WORKSPACE_DIR, "data", "memory"),
+    join(WORKSPACE_DIR, "data", "logs"),
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+}
+
+function makeLoggerStub(): Record<string, unknown> {
+  const stub: Record<string, unknown> = {};
+  for (const m of [
+    "info",
+    "warn",
+    "error",
+    "debug",
+    "trace",
+    "fatal",
+    "silent",
+    "child",
+  ]) {
+    stub[m] = m === "child" ? () => makeLoggerStub() : () => {};
+  }
+  return stub;
+}
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () => makeLoggerStub(),
+}));
+
+afterAll(() => {
+  mock.restore();
+});
+
+import { setOverridesForTesting } from "../../__tests__/feature-flag-test-helpers.js";
+import { invalidateConfigCache } from "../loader.js";
+import { LLMSchema } from "../schemas/llm.js";
+import { seedInferenceProfiles } from "../seed-inference-profiles.js";
+import { reconcileFlagGatedProfiles } from "../sync-gated-profiles.js";
+
+type RawConfig = {
+  llm: {
+    profiles: Record<string, Record<string, unknown>>;
+    profileOrder: string[];
+    activeProfile?: string;
+    advisorProfile?: string;
+  };
+};
+
+function writeConfig(obj: unknown): void {
+  writeFileSync(CONFIG_PATH, JSON.stringify(obj, null, 2) + "\n");
+}
+
+function readConfig(): RawConfig {
+  return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+}
+
+function seedBalancedConfig(): void {
+  writeConfig({ llm: { default: { provider: "anthropic" } } });
+  invalidateConfigCache();
+  seedInferenceProfiles({});
+}
+
+describe("reconcileFlagGatedProfiles", () => {
+  beforeEach(() => {
+    ensureTestDir();
+    if (existsSync(CONFIG_PATH)) rmSync(CONFIG_PATH, { force: true });
+    delete process.env.IS_PLATFORM;
+    setOverridesForTesting({});
+    invalidateConfigCache();
+  });
+
+  afterEach(() => {
+    delete process.env.IS_PLATFORM;
+    setOverridesForTesting({});
+    invalidateConfigCache();
+  });
+
+  test("flag on materializes the managed os-beta profile after balanced", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const raw = readConfig();
+    const osBeta = raw.llm.profiles["os-beta"]!;
+    expect(osBeta.model).toBe("accounts/fireworks/models/glm-5p2");
+    expect(osBeta.provider_connection).toBe("fireworks-managed");
+    expect(osBeta.source).toBe("managed");
+    expect(osBeta.label).toBe("OS Beta");
+
+    const order = raw.llm.profileOrder;
+    expect(order.indexOf("os-beta")).toBe(order.indexOf("balanced") + 1);
+  });
+
+  test("flag on in BYOK mode seeds the os-beta profile disabled", () => {
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const osBeta = readConfig().llm.profiles["os-beta"]!;
+    expect(osBeta.status).toBe("disabled");
+    expect(osBeta.label).toBe("OS Beta (Managed)");
+    expect(osBeta.source).toBe("managed");
+  });
+
+  test("flag on is idempotent across repeated runs", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+    invalidateConfigCache();
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+  });
+
+  test("flag on preserves user overrides on the managed profile", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.profiles["os-beta"]!.label = "My OS Beta";
+    raw.llm.profiles["os-beta"]!.status = "disabled";
+    raw.llm.profiles["os-beta"]!.advisorEnabled = true;
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    reconcileFlagGatedProfiles();
+
+    const after = readConfig().llm.profiles["os-beta"]!;
+    expect(after.label).toBe("My OS Beta");
+    expect(after.status).toBe("disabled");
+    expect(after.advisorEnabled).toBe(true);
+    expect(after.model).toBe("accounts/fireworks/models/glm-5p2");
+  });
+
+  test("flag off removes a managed os-beta and applies fallbacks", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.activeProfile = "os-beta";
+    raw.llm.advisorProfile = "os-beta";
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    expect(after.llm.profiles["os-beta"]).toBeUndefined();
+    expect(after.llm.profileOrder.includes("os-beta")).toBe(false);
+    expect(after.llm.activeProfile).toBe("balanced");
+    expect(after.llm.advisorProfile).toBe("quality-optimized");
+  });
+
+  test("flag off with no os-beta present is a no-op", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": false });
+
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+  });
+
+  test("flag off scrubs os-beta from user mix arms, keeping >= 2-arm mixes", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.profiles["my-mix"] = {
+      source: "user",
+      label: "My Mix",
+      mix: [
+        { profile: "balanced", weight: 70 },
+        { profile: "quality-optimized", weight: 20 },
+        { profile: "os-beta", weight: 30 },
+      ],
+    };
+    raw.llm.profileOrder.push("my-mix");
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    expect(after.llm.profiles["os-beta"]).toBeUndefined();
+    const mix = after.llm.profiles["my-mix"]!;
+    expect(mix.mix).toEqual([
+      { profile: "balanced", weight: 70 },
+      { profile: "quality-optimized", weight: 20 },
+    ]);
+    expect(mix.source).toBe("user");
+    expect(mix.label).toBe("My Mix");
+
+    invalidateConfigCache();
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+  });
+
+  test("flag off removes a two-arm mix that loses os-beta and repoints refs", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.profiles["experiment"] = {
+      source: "user",
+      label: "Experiment",
+      mix: [
+        { profile: "balanced", weight: 50 },
+        { profile: "os-beta", weight: 50 },
+      ],
+    };
+    raw.llm.profileOrder.push("experiment");
+    raw.llm.activeProfile = "experiment";
+    raw.llm.advisorProfile = "os-beta";
+    (raw.llm as Record<string, unknown>).callSites = {
+      mainAgent: { profile: "experiment" },
+    };
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    expect(after.llm.profiles["os-beta"]).toBeUndefined();
+    expect(after.llm.profiles["experiment"]).toBeUndefined();
+    expect(after.llm.profileOrder.includes("os-beta")).toBe(false);
+    expect(after.llm.profileOrder.includes("experiment")).toBe(false);
+    expect(after.llm.activeProfile).toBe("balanced");
+    expect(after.llm.advisorProfile).toBe("quality-optimized");
+    expect(
+      (
+        after.llm as unknown as Record<
+          string,
+          Record<string, Record<string, unknown>>
+        >
+      ).callSites.mainAgent.profile,
+    ).toBeUndefined();
+
+    expect(LLMSchema.safeParse(after.llm).success).toBe(true);
+  });
+
+  test("flag off shortens a three-arm mix to two surviving arms", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    raw.llm.profiles["blend"] = {
+      source: "user",
+      label: "Blend",
+      mix: [
+        { profile: "balanced", weight: 40 },
+        { profile: "os-beta", weight: 30 },
+        { profile: "quality-optimized", weight: 30 },
+      ],
+    };
+    raw.llm.profileOrder.push("blend");
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    expect(after.llm.profiles["os-beta"]).toBeUndefined();
+    expect(after.llm.profiles["blend"]!.mix).toEqual([
+      { profile: "balanced", weight: 40 },
+      { profile: "quality-optimized", weight: 30 },
+    ]);
+
+    expect(LLMSchema.safeParse(after.llm).success).toBe(true);
+  });
+
+  test("flag off clears a call-site profile reference to os-beta", () => {
+    process.env.IS_PLATFORM = "true";
+    seedBalancedConfig();
+    setOverridesForTesting({ "os-beta": true });
+    reconcileFlagGatedProfiles();
+
+    const raw = readConfig();
+    (raw.llm as Record<string, unknown>).callSites = {
+      advisor: { profile: "os-beta", temperature: 0.3 },
+    };
+    writeConfig(raw);
+    invalidateConfigCache();
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(true);
+
+    const after = readConfig();
+    const advisor = (
+      after.llm as unknown as Record<
+        string,
+        Record<string, Record<string, unknown>>
+      >
+    ).callSites.advisor;
+    expect(advisor.profile).toBeUndefined();
+    expect(advisor.temperature).toBe(0.3);
+
+    expect(LLMSchema.safeParse(after.llm).success).toBe(true);
+  });
+
+  test("a user-owned os-beta profile is never touched", () => {
+    process.env.IS_PLATFORM = "true";
+    writeConfig({
+      llm: {
+        default: { provider: "anthropic" },
+        profiles: {
+          "os-beta": {
+            source: "user",
+            label: "Mine",
+            provider: "anthropic",
+            model: "claude-x",
+            provider_connection: "anthropic-personal",
+          },
+        },
+        profileOrder: ["os-beta"],
+      },
+    });
+    invalidateConfigCache();
+    const before = readFileSync(CONFIG_PATH, "utf-8");
+
+    setOverridesForTesting({ "os-beta": true });
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+    expect(readFileSync(CONFIG_PATH, "utf-8")).toBe(before);
+
+    setOverridesForTesting({ "os-beta": false });
+    expect(reconcileFlagGatedProfiles()).toBe(false);
+    expect(readFileSync(CONFIG_PATH, "utf-8")).toBe(before);
+  });
+});

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

@@ -103,7 +103,11 @@ function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
     const entry = flag as Record<string, unknown>;
     if (entry.scope !== "assistant" && entry.scope !== "both") continue;
     if (typeof entry.key !== "string") continue;
-    if (typeof entry.defaultEnabled !== "boolean" && typeof entry.defaultEnabled !== "string") continue;
+    if (
+      typeof entry.defaultEnabled !== "boolean" &&
+      typeof entry.defaultEnabled !== "string"
+    )
+      continue;
 
     result[entry.key as string] = {
       defaultEnabled: entry.defaultEnabled,
@@ -178,6 +182,12 @@ const DEFAULT_INIT_RETRY_BACKOFFS_MS: readonly number[] = [
  * 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
+ * gateway). Callers that mutate persisted state from flag values gate that
+ * work on a `true` result so a failed fetch never resolves a flag to its
+ * registry default and drops user state.
  */
 export async function initFeatureFlagOverrides(options?: {
   retryBackoffsMs?: readonly number[];
@@ -188,8 +198,8 @@ export async function initFeatureFlagOverrides(options?: {
    * instead of blocking startup.
    */
   callTimeoutMs?: number;
-}): Promise<void> {
-  if (isCachedFromGateway()) return;
+}): Promise<boolean> {
+  if (isCachedFromGateway()) return true;
 
   const backoffs = options?.retryBackoffsMs ?? DEFAULT_INIT_RETRY_BACKOFFS_MS;
   const callTimeoutMs = options?.callTimeoutMs;
@@ -205,7 +215,7 @@ export async function initFeatureFlagOverrides(options?: {
       // Re-check after the wait: a concurrent caller (e.g. a test using
       // `setOverridesForTesting`) may have populated the cache while we
       // were sleeping. Bail out so we don't clobber their setup.
-      if (isCachedFromGateway()) return;
+      if (isCachedFromGateway()) return true;
     }
 
     const gatewayOverrides = await fetchOverridesFromGateway(callTimeoutMs);
@@ -217,7 +227,7 @@ export async function initFeatureFlagOverrides(options?: {
           "Feature flag overrides loaded from gateway after retry",
         );
       }
-      return;
+      return true;
     }
   }
 
@@ -230,6 +240,7 @@ export async function initFeatureFlagOverrides(options?: {
       "Feature flag overrides empty after all retries; falling back to registry defaults and fail-closed undeclared flags",
     );
   }
+  return false;
 }
 
 /**
@@ -262,10 +273,14 @@ export function clearFeatureFlagOverridesCache(): void {
  * 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.
+ *
+ * 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<void> {
+export async function refreshOverridesFromGateway(): Promise<boolean> {
   clearFeatureFlagOverridesCache();
-  await initFeatureFlagOverrides({ retryBackoffsMs: [] });
+  return initFeatureFlagOverrides({ retryBackoffsMs: [] });
 }
 
 // ---------------------------------------------------------------------------