@vellumai/assistant 0.11.4-staging.1 → 0.11.4-staging.3

package/src/__tests__/conversation-queue.test.ts

@@ -2988,6 +2988,9 @@ describe("Conversation host attachment directives", () => {
         attachments: [],
         onEvent: (e) => events.push(e),
         requestId: "req-1",
+        // A host attachment read prompts only when a human is present to
+        // answer; presence is declared per turn.
+        isInteractive: true,
       });
       await waitForPendingRun(1);
 
@@ -3058,6 +3061,9 @@ describe("Conversation host attachment directives", () => {
         attachments: [],
         onEvent: (e) => events.push(e),
         requestId: "req-1",
+        // A host attachment read prompts only when a human is present to
+        // answer; presence is declared per turn.
+        isInteractive: true,
       });
       await waitForPendingRun(1);
 
@@ -3923,3 +3929,96 @@ describe("subagent notification user_message_echo suppression", () => {
     await new Promise((r) => setTimeout(r, 10));
   });
 });
+
+describe("drained turns deliver through the conversation sink", () => {
+  beforeEach(() => {
+    pendingRuns = [];
+  });
+
+  test("a confirmation prompt raised in a drained interactive turn reaches the sink", async () => {
+    // The sink is fixed for the conversation's life, so an interactive turn
+    // drained from the queue delivers exactly like a live one: no per-turn
+    // rebinding, nothing for the previous turn's cleanup to clobber. This is
+    // the invariant behind the acp_spawn permission-prompt timeouts (a queued
+    // interactive turn's confirmation_request used to be emitted into a
+    // reset no-op sender and hang until the permission timeout).
+    const sink: AssistantEvent[] = [];
+    const conversation = makeConversation((msg) => sink.push(msg));
+    await conversation.loadFromDb();
+
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: () => {},
+      requestId: "req-1",
+    });
+    await waitForPendingRun(1);
+
+    conversation.enqueueMessage({
+      content: "msg-2",
+      requestId: "req-2",
+      onEvent: () => {},
+      isInteractive: true,
+    });
+
+    await resolveRun(0);
+    await p1;
+    await waitForPendingRun(2);
+
+    // The drained turn is in flight and interactive: presence reads a human.
+    expect(conversation.hasNoClient).toBe(false);
+
+    // A prompt raised now, mid-drained-turn, must land on the sink.
+    void conversation.prompter.prompt(
+      "acp_spawn",
+      { agent: "claude", task: "t" },
+      "high",
+      [],
+      [],
+      undefined,
+      conversation.conversationId,
+      "host",
+      false,
+      undefined,
+      "tool-use-1",
+    );
+    const prompt = sink.find((e) => e.type === "confirmation_request");
+    expect(prompt).toBeDefined();
+    expect((prompt as { toolName: string }).toolName).toBe("acp_spawn");
+    // Settle it so the prompt's timer does not outlive the test.
+    conversation.prompter.denyAllPending();
+
+    await resolveRun(1);
+    // Turn over: nothing is in flight, so no human is asserted present.
+    await waitForCondition(() => conversation.hasNoClient);
+  });
+
+  test("a drained non-interactive turn asserts no human present", async () => {
+    const conversation = makeConversation();
+    await conversation.loadFromDb();
+
+    const p1 = conversation.processMessage({
+      content: "msg-1",
+      attachments: [],
+      onEvent: () => {},
+      requestId: "req-1",
+    });
+    await waitForPendingRun(1);
+
+    conversation.enqueueMessage({
+      content: "msg-2",
+      requestId: "req-2",
+      onEvent: () => {},
+      isInteractive: false,
+    });
+
+    await resolveRun(0);
+    await p1;
+    await waitForPendingRun(2);
+
+    expect(conversation.hasNoClient).toBe(true);
+
+    await resolveRun(1);
+    await new Promise((r) => setTimeout(r, 10));
+  });
+});

package/src/__tests__/conversation-routes-disk-view.test.ts

@@ -149,7 +149,7 @@ function createFakeConversation(conversationId: string): Conversation {
       return this.turnInterfaceContext;
     },
     ensureActorScopedHistory: async () => {},
-    updateClient: () => {},
+    replayActivityState: () => {},
 
     setHostCuProxy(this: { hostCuProxy: unknown }, proxy: unknown) {
       this.hostCuProxy = proxy;

package/src/__tests__/conversation-routes-enabled-plugins.test.ts

@@ -158,7 +158,7 @@ function makeConversation() {
     currentRequestId: undefined,
     queue: { length: 0 },
     setTrustContext: () => {},
-    updateClient: () => {},
+    replayActivityState: () => {},
     emitConfirmationStateChanged: () => {},
     emitActivityState: () => {},
     setTurnChannelContext: () => {},

package/src/__tests__/conversation-routes-guardian-reply.test.ts

@@ -163,7 +163,7 @@ describe("handleSendMessage guardian reply interception", () => {
     const runAgentLoop = mock(async () => undefined);
     const session = {
       setTrustContext: () => {},
-      updateClient: () => {},
+      replayActivityState: () => {},
       emitConfirmationStateChanged: () => {},
       emitActivityState: () => {},
       setTurnChannelContext: () => {},
@@ -253,7 +253,7 @@ describe("handleSendMessage guardian reply interception", () => {
     const runAgentLoop = mock(async () => undefined);
     const session = {
       setTrustContext: () => {},
-      updateClient: () => {},
+      replayActivityState: () => {},
       emitConfirmationStateChanged: () => {},
       emitActivityState: () => {},
       setTurnChannelContext: () => {},
@@ -331,7 +331,7 @@ describe("handleSendMessage guardian reply interception", () => {
     const runAgentLoop = mock(async () => undefined);
     const session = {
       setTrustContext: () => {},
-      updateClient: () => {},
+      replayActivityState: () => {},
       emitConfirmationStateChanged: () => {},
       emitActivityState: () => {},
       setTurnChannelContext: () => {},
@@ -419,7 +419,7 @@ describe("handleSendMessage guardian reply interception", () => {
     const runAgentLoop = mock(async () => undefined);
     const session = {
       setTrustContext: () => {},
-      updateClient: () => {},
+      replayActivityState: () => {},
       emitConfirmationStateChanged: () => {},
       emitActivityState: () => {},
       setTurnChannelContext: () => {},
@@ -507,7 +507,7 @@ describe("handleSendMessage guardian reply interception", () => {
     const runAgentLoop = mock(async () => undefined);
     const session = {
       setTrustContext: () => {},
-      updateClient: () => {},
+      replayActivityState: () => {},
       emitConfirmationStateChanged: () => {},
       emitActivityState: () => {},
       setTurnChannelContext: () => {},
@@ -590,7 +590,7 @@ describe("handleSendMessage guardian reply interception", () => {
     const runAgentLoop = mock(async () => undefined);
     const session = {
       setTrustContext: () => {},
-      updateClient: () => {},
+      replayActivityState: () => {},
       emitConfirmationStateChanged: () => {},
       emitActivityState: () => {},
       setTurnChannelContext: () => {},
@@ -667,7 +667,7 @@ describe("handleSendMessage guardian reply interception", () => {
     const runAgentLoop = mock(async () => undefined);
     const session = {
       setTrustContext: () => {},
-      updateClient: () => {},
+      replayActivityState: () => {},
       emitConfirmationStateChanged: () => {},
       emitActivityState: () => {},
       setTurnChannelContext: () => {},
@@ -746,7 +746,7 @@ describe("handleSendMessage guardian reply interception", () => {
     const runAgentLoop = mock(async () => undefined);
     const session = {
       setTrustContext: () => {},
-      updateClient: () => {},
+      replayActivityState: () => {},
       emitConfirmationStateChanged: () => {},
       emitActivityState: () => {},
       setTurnChannelContext: () => {},
@@ -826,7 +826,7 @@ describe("handleSendMessage guardian reply interception", () => {
     const runAgentLoop = mock(async () => undefined);
     const session = {
       setTrustContext: () => {},
-      updateClient: () => {},
+      replayActivityState: () => {},
       emitConfirmationStateChanged: () => {},
       emitActivityState: () => {},
       setTurnChannelContext: () => {},

package/src/__tests__/conversation-routes-hidden-queue.test.ts

@@ -169,7 +169,7 @@ function makeConversationWithPendingConfirmation(
     setTrustContext(this: { trustContext: unknown }, ctx: unknown) {
       this.trustContext = ctx;
     },
-    updateClient: () => {},
+    replayActivityState: () => {},
     emitConfirmationStateChanged: () => {},
     emitActivityState: () => {},
     setTurnChannelContext: () => {},

package/src/__tests__/conversation-routes-slash-commands.test.ts

@@ -233,7 +233,7 @@ function makeConversation() {
     currentRequestId: undefined,
     queue: { length: 0 },
     setTrustContext: () => {},
-    updateClient: (_fn: unknown, _b: boolean) => {},
+    replayActivityState: () => {},
     emitConfirmationStateChanged: () => {},
     emitActivityState: () => {},
     setTurnChannelContext: () => {},

package/src/__tests__/conversation-slash-queue.test.ts

@@ -62,6 +62,9 @@ mock.module("../persistence/conversation-crud.js", () => ({
   getLastUserTimestampBefore: () => 0,
   reserveMessage: mock(async () => ({ id: "msg-reserve" })),
   updateMessageContent: mock(() => {}),
+  // The drain records the snapshot-stream anchor after each echo. Mocked so a
+  // sink that stamps seqs (the hub) cannot send the real recorder to SQLite.
+  recordConversationPersistedSeq: () => {},
 }));
 
 mock.module("../persistence/conversation-queries.js", () => ({

package/src/__tests__/conversation-surfaces-action-delivery.test.ts

@@ -43,6 +43,7 @@ function makeContext(sent: AssistantEvent[] = []): Conversation & {
   return asConversation({
     conversationId: "conv-1",
     sendToClient: (msg: AssistantEvent) => sent.push(msg),
+    emit: (msg: AssistantEvent) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-activation-emit.test.ts

@@ -69,6 +69,7 @@ function makeContext(
   return {
     conversationId,
     sendToClient: (msg: AssistantEvent) => sent.push(msg),
+    emit: (msg: AssistantEvent) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-app-control.test.ts

@@ -97,6 +97,7 @@ function buildMockContext(
           } as Conversation["currentTurnAuthContext"])
         : undefined,
     sendToClient: () => {},
+    emit: () => {},
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/conversation-surfaces-app-open.test.ts

@@ -29,7 +29,7 @@ function makeContext(
     channelCapabilities:
       options.channelCapabilities &&
       mockChannelCapabilities(options.channelCapabilities),
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-data-persist.test.ts

@@ -57,7 +57,7 @@ import { asConversation } from "./helpers/mock-conversation.js";
 function makeContext(sent: AssistantEvent[] = []): Conversation {
   return asConversation({
     conversationId: "conv-persist-1",
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-history-restored-completion.test.ts

@@ -124,13 +124,17 @@ type EnqueueResult = { queued: boolean; requestId: string; rejected?: boolean };
 
 function makeContext(
   enqueueResult: EnqueueResult = { queued: false, requestId: "req-1" },
-  overrides: { trustContext?: TrustContext; queueDepth?: number } = {},
+  overrides: {
+    trustContext?: TrustContext;
+    queueDepth?: number;
+    emit?: (msg: AssistantEvent) => void;
+  } = {},
 ): Conversation & { enqueuedContents: string[] } {
   const enqueuedContents: string[] = [];
   return asConversation({
     conversationId: CONVERSATION_ID,
     trustContext: overrides.trustContext ?? GUARDIAN_TRUST,
-    sendToClient: () => {},
+    emit: overrides.emit ?? (() => {}),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,
@@ -885,11 +889,12 @@ describe("surface completion when the persisted write does not land", () => {
   test("a ui_dismiss completion whose write throws stays retryable", async () => {
     const surfaceId = "surface-dismiss-persist-throws-1";
     seedSurfaceRow(surfaceId, "choice");
-    const ctx = makeContext();
     const sentToClient: AssistantEvent[] = [];
-    ctx.sendToClient = (msg) => {
-      sentToClient.push(msg);
-    };
+    const ctx = makeContext(undefined, {
+      emit: (msg) => {
+        sentToClient.push(msg);
+      },
+    });
     seedAnsweredSurface(ctx, surfaceId);
     persistError = new Error("database is locked");
 
@@ -919,11 +924,12 @@ describe("surface completion when the persisted write does not land", () => {
   test("a ui_dismiss completion that lands clears the live state", async () => {
     const surfaceId = "surface-dismiss-persist-lands-1";
     seedSurfaceRow(surfaceId, "choice");
-    const ctx = makeContext();
     const sentToClient: AssistantEvent[] = [];
-    ctx.sendToClient = (msg) => {
-      sentToClient.push(msg);
-    };
+    const ctx = makeContext(undefined, {
+      emit: (msg) => {
+        sentToClient.push(msg);
+      },
+    });
     seedAnsweredSurface(ctx, surfaceId);
 
     const result = await surfaceProxyResolver(ctx, "ui_dismiss", {
@@ -942,11 +948,12 @@ describe("surface completion when the persisted write does not land", () => {
   test("a ui_dismiss with no recorded action clears the live state even when the write throws", async () => {
     const surfaceId = "surface-dismiss-no-action-1";
     seedSurfaceRow(surfaceId, "card");
-    const ctx = makeContext();
     const sentToClient: AssistantEvent[] = [];
-    ctx.sendToClient = (msg) => {
-      sentToClient.push(msg);
-    };
+    const ctx = makeContext(undefined, {
+      emit: (msg) => {
+        sentToClient.push(msg);
+      },
+    });
     ctx.pendingSurfaceActions.set(surfaceId, { surfaceType: "card" });
     ctx.surfaceState.set(surfaceId, { surfaceType: "card", data: {} });
     persistError = new Error("database is locked");

package/src/__tests__/conversation-surfaces-queued-emit.test.ts

@@ -22,6 +22,7 @@ function makeQueuedContext(): Conversation {
   return asConversation({
     conversationId: CONV_ID,
     sendToClient: () => {},
+    emit: () => {},
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-standalone-payloads.test.ts

@@ -65,6 +65,7 @@ function createMockContext(
         })
       : undefined,
     sendToClient: (msg: AssistantEvent) => sentMessages.push(msg),
+    emit: (msg: AssistantEvent) => sentMessages.push(msg),
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/conversation-surfaces-standalone.test.ts

@@ -53,6 +53,7 @@ function createMockContext(
         })
       : undefined,
     sendToClient: (msg: AssistantEvent) => sentMessages.push(msg),
+    emit: (msg: AssistantEvent) => sentMessages.push(msg),
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/conversation-surfaces-state-update.test.ts

@@ -26,7 +26,7 @@ function makeContext(opts?: { sent?: AssistantEvent[] }): Conversation & {
 
   return asConversation({
     conversationId: "test-session",
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-table-action.test.ts

@@ -49,7 +49,7 @@ function makeContext(): Conversation & {
 
   return asConversation({
     conversationId: "test-convo",
-    sendToClient: (msg) => sentMessages.push(msg),
+    emit: (msg) => sentMessages.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-task-progress.test.ts

@@ -26,7 +26,7 @@ function makeContext(
     conversationId: "session-1",
     channelCapabilities:
       channelCapabilities && mockChannelCapabilities(channelCapabilities),
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-tool-setup-app-refresh.test.ts

@@ -94,7 +94,7 @@ function makeCtx(overrides: Partial<Conversation> = {}): Conversation {
     workingDir: "/tmp/test",
     getTurnActorPrincipalId: () => undefined,
     abortController: null,
-    sendToClient: mock(() => {}),
+    emit: mock(() => {}),
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/conversation-tool-setup-attribution.test.ts

@@ -101,7 +101,7 @@ function makeCtx(overrides: Partial<Conversation> = {}): Conversation {
     workingDir: "/tmp/test",
     getTurnActorPrincipalId: () => undefined,
     abortController: null,
-    sendToClient: mock(() => {}),
+    emit: mock(() => {}),
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/cu-unified-flow.test.ts

@@ -97,6 +97,7 @@ function buildMockContext(
           } as Conversation["currentTurnAuthContext"])
         : undefined,
     sendToClient: () => {},
+    emit: () => {},
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/document-sync-tags.test.ts

@@ -3,8 +3,6 @@
  * the Library and the per-conversation assets list converge on every surface.
  * Read routes and rejected writes must stay silent.
  */
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 
 import type { AssistantEventEnvelope } from "../api/index.js";
@@ -24,9 +22,6 @@ import { resetDbForTesting } from "./db-test-helpers.js";
 
 await initializeDb();
 
-const workspaceDir = process.env.VELLUM_WORKSPACE_DIR!;
-const notesDir = join(workspaceDir, "sync-notes");
-
 const CONVERSATION_ID = "conv-doc-sync";
 const OTHER_CONVERSATION_ID = "conv-doc-sync-other";
 const MISSING_CONVERSATION_ID = "conv-doc-sync-missing";
@@ -110,15 +105,6 @@ async function saveViaRoute(
   });
 }
 
-async function openWorkspaceFile(
-  path: string,
-  conversationId = CONVERSATION_ID,
-): Promise<unknown> {
-  return await invoke("documentForWorkspaceFile", {
-    body: { path, conversationId },
-  });
-}
-
 async function linkViaRoute(
   surfaceId: string,
   conversationId: string,
@@ -136,12 +122,9 @@ beforeEach(() => {
   db.run("DELETE FROM conversations");
   createConversation({ id: CONVERSATION_ID });
   createConversation({ id: OTHER_CONVERSATION_ID });
-  rmSync(notesDir, { recursive: true, force: true });
-  mkdirSync(notesDir, { recursive: true });
 });
 
 afterAll(() => {
-  rmSync(notesDir, { recursive: true, force: true });
   resetDbForTesting();
 });
 
@@ -220,67 +203,9 @@ describe("document write routes publish documents:list", () => {
     expect(events).toHaveLength(1);
     expect("originClientId" in events[0].message).toBe(false);
   });
-
-  test("binding a workspace file publishes without an origin so the caller is not suppressed", async () => {
-    // `viewer-store.loadWorkspaceFileDocument` creates the row and invalidates
-    // nothing, so the client that opened the file is the one that most needs
-    // the invalidation.
-    writeFileSync(join(notesDir, "plan.md"), "# Plan");
-
-    const events = await captureSyncEvents(() =>
-      invoke("documentForWorkspaceFile", {
-        body: { path: "sync-notes/plan.md", conversationId: CONVERSATION_ID },
-        headers: { "x-vellum-client-id": "client-abc" },
-      }),
-    );
-
-    expect(events).toHaveLength(1);
-    expect("originClientId" in events[0].message).toBe(false);
-  });
-
-  test("binding a workspace file to a new document publishes", async () => {
-    writeFileSync(join(notesDir, "plan.md"), "# Plan");
-
-    const events = await captureSyncEvents(() =>
-      openWorkspaceFile("sync-notes/plan.md"),
-    );
-    expectDocumentsChanged(events);
-  });
-
-  test("reopening the file from another conversation publishes the new link", async () => {
-    writeFileSync(join(notesDir, "plan.md"), "# Plan");
-    await openWorkspaceFile("sync-notes/plan.md");
-
-    const events = await captureSyncEvents(() =>
-      openWorkspaceFile("sync-notes/plan.md", OTHER_CONVERSATION_ID),
-    );
-    expectDocumentsChanged(events);
-  });
-
-  test("refreshing a document whose file changed on disk publishes", async () => {
-    const filePath = join(notesDir, "plan.md");
-    writeFileSync(filePath, "# Plan");
-    await openWorkspaceFile("sync-notes/plan.md");
-    writeFileSync(filePath, "# Plan\n\nedited outside the editor");
-
-    const events = await captureSyncEvents(() =>
-      openWorkspaceFile("sync-notes/plan.md"),
-    );
-    expectDocumentsChanged(events);
-  });
 });
 
 describe("document routes that change nothing the list shows stay silent", () => {
-  test("reopening an unchanged, already-linked file publishes nothing", async () => {
-    writeFileSync(join(notesDir, "plan.md"), "# Plan");
-    await openWorkspaceFile("sync-notes/plan.md");
-
-    const events = await captureSyncEvents(() =>
-      openWorkspaceFile("sync-notes/plan.md"),
-    );
-    expect(events).toEqual([]);
-  });
-
   test("a save rejected by validation publishes nothing", async () => {
     const events = await captureSyncEvents(async () => {
       await expect(saveViaRoute({ title: undefined })).rejects.toThrow(

package/src/__tests__/gateway-only-guard.test.ts

@@ -83,11 +83,8 @@ function isGatewayInternal(filePath: string): boolean {
 /** Additional files allowed for the interpolated-port check only (use gateway port, not runtime). */
 const INTERPOLATED_PORT_ALLOWLIST = new Set([
   "clients/macos/src/main/bundle-flow.ts",
-  // Electron main bridges the host proxy to a local assistant's gateway
-  // (gatewayPort) over loopback with a Guardian-minted gateway token — same
-  // class as bundle-flow.ts. Added with #34049 (host proxy for cloud/managed
-  // assistants); the allowlist entry was missed there.
-  "clients/macos/src/main/host-proxy-router.ts",
+  // Desktop clients connect to local assistants through their loopback gateway.
+  "packages/electron-desktop/src/host-proxy/router.ts",
 ]);
 
 /** Shared violation filter: exempt test files, gateway internals, and allowlisted paths. */

package/src/__tests__/http-user-message-parity.test.ts

@@ -189,7 +189,7 @@ const _testAuthContext: AuthContext = {
 function makeConversation(overrides: Record<string, unknown> = {}) {
   return {
     setTrustContext: () => {},
-    updateClient: () => {},
+    replayActivityState: () => {},
     setHostBrowserProxy: () => {},
     setHostCuProxy: () => {},
     setHostAppControlProxy: () => {},

package/src/__tests__/init-feature-flag-overrides.test.ts

@@ -11,6 +11,7 @@ import {
   clearFeatureFlagOverridesCache,
   initFeatureFlagOverrides,
   isAssistantFeatureFlagEnabled,
+  refreshOverridesFromGateway,
 } from "../config/assistant-feature-flags.js";
 import { mockGatewayIpc, resetMockGatewayIpc } from "./mock-gateway-ipc.js";
 
@@ -110,3 +111,51 @@ describe("initFeatureFlagOverrides", () => {
     expect(isAssistantFeatureFlagEnabled("second-call", config)).toBe(false);
   });
 });
+
+describe("refreshOverridesFromGateway", () => {
+  it("replaces the cache with the new gateway values", async () => {
+    mockGatewayIpc({ "moving-flag": true });
+    await initFeatureFlagOverrides();
+
+    resetMockGatewayIpc();
+    mockGatewayIpc({ "moving-flag": false });
+
+    expect(await refreshOverridesFromGateway()).toBe(true);
+
+    const config = {} as any;
+    expect(isAssistantFeatureFlagEnabled("moving-flag", config)).toBe(false);
+  });
+
+  it("keeps the last known values when the refresh fails", async () => {
+    mockGatewayIpc({ "moving-flag": true });
+    await initFeatureFlagOverrides();
+
+    resetMockGatewayIpc();
+    mockGatewayIpc(null, { error: true });
+
+    expect(await refreshOverridesFromGateway()).toBe(false);
+
+    // A failed refresh must not drop the flag to its registry default: a
+    // value the assistant selects behavior from (an experiment arm, a kill
+    // switch) would otherwise flip on one timed-out IPC call.
+    const config = {} as any;
+    expect(isAssistantFeatureFlagEnabled("moving-flag", config)).toBe(true);
+  });
+
+  it("keeps the cache readable for the whole call", async () => {
+    mockGatewayIpc({ "moving-flag": true });
+    await initFeatureFlagOverrides();
+
+    resetMockGatewayIpc();
+    mockGatewayIpc({ "moving-flag": false });
+
+    const config = {} as any;
+    const inFlight = refreshOverridesFromGateway();
+    // A sync read landing mid-refresh sees the previous values, never an
+    // empty cache.
+    expect(isAssistantFeatureFlagEnabled("moving-flag", config)).toBe(true);
+
+    await inFlight;
+    expect(isAssistantFeatureFlagEnabled("moving-flag", config)).toBe(false);
+  });
+});