@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/daemon/host-transfer-proxy.ts

@@ -663,19 +663,22 @@ export class HostTransferProxy {
     const transferId = interaction.metadata?.transferId as string | undefined;
     if (transferId) this.transfers.delete(transferId);
     pendingInteractions.resolve(requestId, "cancelled");
+    const { conversationId } = interaction;
     try {
-      broadcastMessage(
-        {
-          type: "host_transfer_cancel",
-          requestId,
-          conversationId: interaction.conversationId,
-          ...(interaction.targetClientId != null
-            ? { targetClientId: interaction.targetClientId }
-            : {}),
-        },
-        interaction.conversationId,
-        { targetClientId: interaction.targetClientId },
-      );
+      if (conversationId !== undefined) {
+        broadcastMessage(
+          {
+            type: "host_transfer_cancel",
+            requestId,
+            conversationId,
+            ...(interaction.targetClientId != null
+              ? { targetClientId: interaction.targetClientId }
+              : {}),
+          },
+          conversationId,
+          { targetClientId: interaction.targetClientId },
+        );
+      }
     } catch {
       // Best-effort cancel notification
     }
@@ -719,19 +722,22 @@ export class HostTransferProxy {
       const transferId = entry.metadata?.transferId as string | undefined;
       if (transferId) this.transfers.delete(transferId);
       pendingInteractions.resolve(entry.requestId, "cancelled");
+      const { conversationId } = entry;
       try {
-        broadcastMessage(
-          {
-            type: "host_transfer_cancel",
-            requestId: entry.requestId,
-            conversationId: entry.conversationId,
-            ...(entry.targetClientId != null
-              ? { targetClientId: entry.targetClientId }
-              : {}),
-          },
-          entry.conversationId,
-          { targetClientId: entry.targetClientId },
-        );
+        if (conversationId !== undefined) {
+          broadcastMessage(
+            {
+              type: "host_transfer_cancel",
+              requestId: entry.requestId,
+              conversationId,
+              ...(entry.targetClientId != null
+                ? { targetClientId: entry.targetClientId }
+                : {}),
+            },
+            conversationId,
+            { targetClientId: entry.targetClientId },
+          );
+        }
       } catch {
         // Best-effort cancel notification
       }

package/src/daemon/lifecycle.ts

@@ -84,6 +84,7 @@ import {
   setUsageTelemetryReporter,
   UsageTelemetryReporter,
 } from "../telemetry/usage-telemetry-reporter.js";
+import { syncFlagGatedTools } from "../tools/registry.js";
 import { registerBuiltinTtsProviders } from "../tts/providers/register-builtins.js";
 import { getDeviceId } from "../util/device-id.js";
 import { getLogger, initLogger } from "../util/logger.js";
@@ -97,6 +98,7 @@ import {
   listWorkItems,
   updateWorkItem,
 } from "../work-items/work-item-store.js";
+import { getWorkflowRunManager } from "../workflows/run-manager.js";
 import { repairAdaptiveThinkingOnManagedProfiles } from "../workspace/adaptive-thinking-repair.js";
 import { WorkspaceHeartbeatService } from "../workspace/heartbeat-service.js";
 import { WORKSPACE_MIGRATIONS } from "../workspace/migrations/registry.js";
@@ -358,9 +360,14 @@ export async function runDaemon(): Promise<void> {
     // so a slow or unreachable gateway doesn't delay daemon startup (the
     // IPC call has a 3s connect + 5s call timeout that would otherwise
     // stall the critical path).
-    void initFeatureFlagOverrides().catch((err) =>
-      log.warn({ err }, "Background feature flag init failed"),
-    );
+    // After the async fetch resolves, (re)register any flag-gated tools
+    // (`workflows`, `ces-tools`): `initializeTools()` runs during startup before
+    // this fetch completes, so without this follow-up sync a flag-enabled
+    // assistant would not expose the gated tools until a restart (which can lose
+    // the same race). Enable-direction only; chained so it sees the fresh cache.
+    void initFeatureFlagOverrides()
+      .then(() => syncFlagGatedTools())
+      .catch((err) => log.warn({ err }, "Background feature flag init failed"));
 
     startGatewayFlagListener();
 
@@ -951,6 +958,26 @@ export async function runDaemon(): Promise<void> {
       log.error({ err }, "Schedule recovery failed — continuing startup");
     }
 
+    // Reconcile workflow runs orphaned by a crash: any row still `running` was
+    // in flight when the process died (the engine always finishes its row on
+    // exit), so flip it to `interrupted` to make it eligible for an explicit
+    // resume. Status only — accounting counters are preserved. Never blocks
+    // startup on failure.
+    try {
+      const reconciled = getWorkflowRunManager().reconcileOrphanedRuns();
+      if (reconciled > 0) {
+        log.info(
+          { reconciled },
+          "Reconciled orphaned workflow runs to interrupted",
+        );
+      }
+    } catch (err) {
+      log.error(
+        { err },
+        "Workflow run reconciliation failed — continuing startup",
+      );
+    }
+
     const scheduler = startScheduler(
       async (conversationId, message, options) => {
         await processMessage(
@@ -967,6 +994,9 @@ export async function runDaemon(): Promise<void> {
                     }
                   : {}),
                 ...(options.taskRunId ? { taskRunId: options.taskRunId } : {}),
+                ...(options.overrideProfile
+                  ? { overrideProfile: options.overrideProfile }
+                  : {}),
               }
             : undefined,
         );
@@ -1251,6 +1281,13 @@ export async function runDaemon(): Promise<void> {
       log.warn({ err }, "Assistant symlink installation failed — continuing");
     }
 
+    // Seed preloaded apps (personal landing page) in background (non-blocking).
+    void import("../memory/preloaded-apps.js")
+      .then(({ seedPreloadedApps }) => seedPreloadedApps(config))
+      .catch((err) =>
+        log.warn({ err }, "Preloaded app seeding failed — continuing"),
+      );
+
     // Download embedding runtime in background (non-blocking).
     // If download fails, local embeddings gracefully fall back to cloud backends.
     void (async () => {

package/src/daemon/message-protocol.ts

@@ -46,6 +46,7 @@ export * from "./message-types/sync.js";
 export * from "./message-types/upgrades.js";
 export * from "./message-types/web-activity.js";
 export * from "./message-types/work-items.js";
+export * from "./message-types/workflows.js";
 export * from "./message-types/workspace.js";
 
 // Import domain-level union aliases for composition
@@ -135,6 +136,7 @@ import type {
   _WorkItemsClientMessages,
   _WorkItemsServerMessages,
 } from "./message-types/work-items.js";
+import type { _WorkflowsServerMessages } from "./message-types/workflows.js";
 import type {
   _WorkspaceClientMessages,
   _WorkspaceServerMessages,
@@ -208,6 +210,7 @@ export type ServerMessage =
   | _UpgradesServerMessages
   | _AcpServerMessages
   | _BookmarksServerMessages
+  | _WorkflowsServerMessages
   | DiskPressureStatusChangedEvent
   | SubagentEvent;
 

package/src/daemon/message-types/messages.ts

@@ -2,6 +2,7 @@
 
 import type { AssistantActivityStateEvent } from "../../api/events/assistant-activity-state.js";
 import type { AssistantTextDeltaEvent } from "../../api/events/assistant-text-delta.js";
+import type { AssistantThinkingDeltaEvent } from "../../api/events/assistant-thinking-delta.js";
 import type { AssistantTurnStartEvent } from "../../api/events/assistant-turn-start.js";
 import type { ConfirmationRequestEvent } from "../../api/events/confirmation-request.js";
 import type { ErrorEvent } from "../../api/events/error.js";
@@ -76,15 +77,6 @@ export interface SuggestionRequest {
 
 // === Server → Client ===
 
-export interface AssistantThinkingDelta {
-  type: "assistant_thinking_delta";
-  thinking: string;
-  conversationId?: string;
-  /** Database ID of the assistant message this thinking delta belongs to.
-   *  Same semantics as `AssistantTextDeltaEvent.messageId`. */
-  messageId?: string;
-}
-
 export interface ToolInputDelta {
   type: "tool_input_delta";
   toolName: string;
@@ -160,7 +152,7 @@ export type _MessagesServerMessages =
   | UserMessageEchoEvent
   | AssistantTurnStartEvent
   | AssistantTextDeltaEvent
-  | AssistantThinkingDelta
+  | AssistantThinkingDeltaEvent
   | ToolUseStartEvent
   | ToolUsePreviewStartEvent
   | ToolOutputChunkEvent

package/src/daemon/message-types/workflows.ts

@@ -0,0 +1,49 @@
+// Workflow orchestration run lifecycle events.
+//
+// Emitted by the `WorkflowRunManager` (run-manager.ts) as a workflow run
+// progresses and completes. These are server → client push events only — the
+// run is launched via the workflow tool / scheduler / routes (later PRs), not
+// via a client message in this union.
+
+import type { WorkflowRunStatus } from "../../workflows/journal-store.js";
+
+// === Server → Client ===
+
+/**
+ * Progress push for an in-flight workflow run. Maps the engine's
+ * `onProgress` (`phase`/`log`) callback plus the current usage snapshot into a
+ * single wire event. `phase` carries the latest `phase(title)`; `message`
+ * carries the latest `log(msg)`; only one is set per emission.
+ */
+export interface WorkflowProgress {
+  type: "workflow_progress";
+  runId: string;
+  /** Latest phase title, when this emission came from a `phase(...)` call. */
+  phase?: string;
+  /** Run label (the workflow's `meta.name`), for client display. */
+  label?: string;
+  /** Live agent count at emission time. */
+  agentsSpawned: number;
+  /** Latest log line, when this emission came from a `log(...)` call. */
+  message?: string;
+}
+
+/**
+ * Terminal push for a workflow run. Carries the final status, counts, token
+ * usage, and a human-readable result/error summary the originating
+ * conversation also receives via an agent wake.
+ */
+export interface WorkflowCompleted {
+  type: "workflow_completed";
+  runId: string;
+  status: WorkflowRunStatus;
+  agentsSpawned: number;
+  inputTokens: number;
+  outputTokens: number;
+  /** Human-readable result-or-error summary. */
+  summary?: string;
+}
+
+// --- Domain-level union aliases (consumed by the barrel file) ---
+
+export type _WorkflowsServerMessages = WorkflowProgress | WorkflowCompleted;

package/src/daemon/parse-actual-tokens-from-error.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, test } from "bun:test";
 
 import { ContextOverflowError } from "../providers/types.js";
-import { parseActualTokensFromError } from "./parse-actual-tokens-from-error.js";
+import {
+  looksLikeContextOverflowError,
+  parseActualTokensFromError,
+} from "./parse-actual-tokens-from-error.js";
 
 describe("parseActualTokensFromError", () => {
   test("returns null for null input", () => {
@@ -125,3 +128,61 @@ describe("parseActualTokensFromError", () => {
     expect(parseActualTokensFromError(err)).toBe(242201);
   });
 });
+
+describe("looksLikeContextOverflowError", () => {
+  test("matches the typed ContextOverflowError even without a parseable message", () => {
+    const err = new ContextOverflowError("context window exceeded", "openai");
+    expect(looksLikeContextOverflowError(err)).toBe(true);
+  });
+
+  test("matches a REWRAPPED plain Error carrying an Anthropic-style message", () => {
+    // Managed-proxy/adapter paths rewrap overflow rejections into untyped
+    // errors — the heuristic must still recognize them.
+    const err = new Error(
+      "Provider API error (400): prompt is too long: 250000 tokens > 200000 maximum",
+    );
+    expect(looksLikeContextOverflowError(err)).toBe(true);
+  });
+
+  test("matches a rewrapped OpenAI-style message", () => {
+    expect(
+      looksLikeContextOverflowError(
+        new Error("too many input tokens: 150000 > 128000"),
+      ),
+    ).toBe(true);
+  });
+
+  test("matches context_length_exceeded / maximum-context-length phrasings", () => {
+    expect(
+      looksLikeContextOverflowError(new Error("context_length_exceeded")),
+    ).toBe(true);
+    expect(
+      looksLikeContextOverflowError(
+        new Error("This model's maximum context length is 128000 tokens"),
+      ),
+    ).toBe(true);
+  });
+
+  test("accepts a raw string message", () => {
+    expect(
+      looksLikeContextOverflowError(
+        "prompt is too long: 242201 tokens > 200000 maximum",
+      ),
+    ).toBe(true);
+  });
+
+  test("rejects unrelated errors, strings, and nullish input", () => {
+    expect(looksLikeContextOverflowError(new Error("socket hang up"))).toBe(
+      false,
+    );
+    expect(looksLikeContextOverflowError("something went wrong")).toBe(false);
+    expect(looksLikeContextOverflowError(null)).toBe(false);
+    expect(looksLikeContextOverflowError(undefined)).toBe(false);
+  });
+
+  test("does not misread arbitrary numeric comparisons as overflow", () => {
+    expect(
+      looksLikeContextOverflowError(new Error("retry budget: 5 > 3 attempts")),
+    ).toBe(false);
+  });
+});

package/src/daemon/parse-actual-tokens-from-error.ts

@@ -30,13 +30,52 @@ export function parseActualTokensFromError(
   }
 
   // Untyped path — accept either an Error or a string.
+  return parseFromMessage(extractMessage(errorOrMessage));
+}
+
+/**
+ * Message patterns that identify a provider context-overflow rejection.
+ * Covers the typed wrapper's source patterns plus common provider phrasings
+ * that adapter paths (e.g. managed-proxy rewrappers) surface as untyped
+ * errors:
+ *   "prompt is too long: 242201 tokens > 200000 maximum"   (Anthropic)
+ *   "too many input tokens: 242201 > 200000"                (OpenAI)
+ *   "context_length_exceeded" / "maximum context length"    (OpenAI-compat)
+ */
+const OVERFLOW_MESSAGE_PATTERNS: readonly RegExp[] = [
+  /prompt is too long/i,
+  /too many (?:input )?tokens/i,
+  /context[_\s-]?length[_\s-]?exceeded/i,
+  /maximum context length/i,
+  /\d[\d,]*\s*tokens?\s*[>≥]\s*\d/i,
+];
+
+/**
+ * Heuristic context-overflow check that also catches REWRAPPED provider
+ * errors. `isContextOverflowError` only matches the typed
+ * `ContextOverflowError` wrapper; adapter layers (managed-proxy rewrappers,
+ * retry shims) can re-throw the same rejection as a plain `Error`, hiding the
+ * typed signal. Callers that must not misread an overflow as a clean
+ * no-output stop (e.g. the suppressed-compaction agent-wake path) should use
+ * this instead of the bare typed check.
+ *
+ * Accepts the same inputs as {@link parseActualTokensFromError}: a typed
+ * error, a plain `Error`/object with a `message`, or a raw string.
+ */
+export function looksLikeContextOverflowError(err: unknown): boolean {
+  if (isContextOverflowError(err)) return true;
+  const message = extractMessage(err);
+  if (message === null) return false;
+  return OVERFLOW_MESSAGE_PATTERNS.some((pattern) => pattern.test(message));
+}
+
+/** Pull a message string out of an untyped error-ish value, if possible. */
+function extractMessage(errorOrMessage: unknown): string | null {
   if (errorOrMessage == null) return null;
-  if (typeof errorOrMessage === "string") {
-    return parseFromMessage(errorOrMessage);
-  }
+  if (typeof errorOrMessage === "string") return errorOrMessage;
   if (typeof errorOrMessage === "object" && "message" in errorOrMessage) {
     const msg = (errorOrMessage as { message?: unknown }).message;
-    if (typeof msg === "string") return parseFromMessage(msg);
+    if (typeof msg === "string") return msg;
   }
   return null;
 }

package/src/daemon/process-message.ts

@@ -534,6 +534,9 @@ export async function processMessage(
       isInteractive: options?.isInteractive ?? false,
       isUserMessage: true,
       ...(options?.callSite ? { callSite: options.callSite } : {}),
+      ...(options?.overrideProfile
+        ? { overrideProfile: options.overrideProfile }
+        : {}),
     });
   } finally {
     if (
@@ -591,6 +594,9 @@ export async function processMessageInBackground(
       isInteractive: options?.isInteractive ?? false,
       isUserMessage: true,
       ...(options?.callSite ? { callSite: options.callSite } : {}),
+      ...(options?.overrideProfile
+        ? { overrideProfile: options.overrideProfile }
+        : {}),
     })
     .finally(() => {
       if (

package/src/daemon/tool-setup-types.ts

@@ -8,6 +8,54 @@ import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { SurfaceConversationContext } from "./conversation-surfaces.js";
 import type { TrustContext } from "./trust-context.js";
 
+/**
+ * How a subagent/wake tool allowlist is enforced.
+ *
+ * - `"wire"` (default): filter the tool definitions sent to the provider so
+ *   the model never sees non-allowlisted tools. Smaller request, but the
+ *   tool array no longer byte-matches the conversation's normal turns, so
+ *   the provider prompt-cache prefix (`tools → system → messages`) cannot
+ *   be reused.
+ * - `"execution"`: keep the conversation's full tool surface on the wire
+ *   (preserving cache parity with the source conversation's turns) and
+ *   enforce the allowlist at execution time — a call to a non-allowlisted
+ *   tool returns an error tool_result without ever invoking the tool's
+ *   executor.
+ */
+export type SubagentToolGateMode = "wire" | "execution";
+
+/**
+ * Client-context inputs frozen for tool-DEFINITION resolution during a wake
+ * that runs with `subagentToolGateMode: "execution"`.
+ *
+ * Execution gate mode exists to keep the wire tool array byte-identical to
+ * the source conversation's live turns (see {@link SubagentToolGateMode}),
+ * but the definitions themselves are resolved from the live context: a
+ * fork-retrospective wake hydrates clientless (`hasNoClient = true`, no
+ * transport interface, no channel capabilities), which drops client-gated
+ * tools (`host_*`, `ui_*`, `app_open`, `request_system_permission`) from
+ * the wire definitions and breaks the cache prefix anyway. When this pin is
+ * set on the conversation, `isToolActiveForContext` reads `hasNoClient` and
+ * `transportInterface` exclusively from the pin and treats channel
+ * capabilities as unset — an absent optional field pins the value to
+ * `undefined`; there is no fall-through to the live conversation state.
+ * (Interactive-interface turns never set channel capabilities, so unset IS
+ * parity for desktop/web sources; channel-routed sources resolve every tool
+ * gate identically under `hasNoClient: true` with or without them.)
+ *
+ * Tool-definition resolution ONLY. The executor callback and host-proxy
+ * attachment paths never read the pin, so it cannot make a host tool
+ * runnable: in execution gate mode every non-allowlisted call is rejected
+ * before its executor runs, so a pinned-in tool can appear on the wire but
+ * can never execute.
+ */
+export interface WakeToolContextPin {
+  /** The source conversation's live-turn `hasNoClient` value. */
+  hasNoClient: boolean;
+  /** The interface the source's live turns ran on (e.g. `"macos"`). */
+  transportInterface?: InterfaceId;
+}
+
 /**
  * Subset of Conversation state that the tool executor callback reads at
  * call time (not construction time). These are captured by the
@@ -21,6 +69,15 @@ export interface ToolSetupContext extends SurfaceConversationContext {
   abortController: AbortController | null;
   /** When set, only tools in this set may execute during the current turn. */
   allowedToolNames?: Set<string>;
+  /** When set, the subagent/wake tool allowlist (see {@link subagentToolGateMode}). */
+  subagentAllowedTools?: Set<string>;
+  /**
+   * How {@link subagentAllowedTools} is enforced. Absent or `"wire"` keeps
+   * the historical behavior (definitions filtered before the provider
+   * request); `"execution"` keeps the full tool surface on the wire and
+   * rejects non-allowlisted calls in the executor callback instead.
+   */
+  subagentToolGateMode?: SubagentToolGateMode;
   /** Turn-scoped disk-pressure cleanup mode flag. */
   diskPressureCleanupModeActive?: boolean;
   /** True when the conversation has no connected client (HTTP-only path). */

package/src/daemon/wake-conversation-ops.ts

@@ -25,6 +25,10 @@ import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { getLogger } from "../util/logger.js";
 import type { Conversation } from "./conversation.js";
 import type { ServerMessage } from "./message-protocol.js";
+import type {
+  SubagentToolGateMode,
+  WakeToolContextPin,
+} from "./tool-setup-types.js";
 
 const log = getLogger("wake-conversation-ops");
 
@@ -256,14 +260,28 @@ export async function persistWakeTailMessage(
  * reusing the conversation's subagent allowlist slot. Returns a restore
  * callback that reinstates the previous allowlist so the wake can release
  * the scope before any queued user turn is drained.
+ *
+ * `gateMode` controls how the allowlist is enforced — see
+ * {@link SubagentToolGateMode}. `toolContextPin`, when provided
+ * (execution-gate-mode cache-parity wakes), freezes the client-context
+ * inputs for tool-definition resolution — see {@link WakeToolContextPin}.
+ * Both are set and restored alongside the allowlist.
  */
 export function scopeWakeAllowedTools(
   conversation: Conversation,
   tools: ReadonlySet<string>,
+  gateMode: SubagentToolGateMode = "wire",
+  toolContextPin?: WakeToolContextPin,
 ): () => void {
   const previous = conversation.subagentAllowedTools;
+  const previousGateMode = conversation.subagentToolGateMode;
+  const previousToolContextPin = conversation.toolContextPin;
   conversation.setSubagentAllowedTools(new Set(tools));
+  conversation.subagentToolGateMode = gateMode;
+  conversation.toolContextPin = toolContextPin;
   return () => {
     conversation.setSubagentAllowedTools(previous);
+    conversation.subagentToolGateMode = previousGateMode;
+    conversation.toolContextPin = previousToolContextPin;
   };
 }

package/src/heartbeat/heartbeat-run-store.ts

@@ -1,4 +1,4 @@
-import { desc, eq, sql } from "drizzle-orm";
+import { desc, eq, lt, sql } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getDb } from "../memory/db-connection.js";
@@ -272,12 +272,18 @@ export function countRecentConsecutiveRuns(maxToCheck: number): number {
 
 /**
  * List heartbeat runs ordered by `scheduledFor` descending.
+ * When `before` is set, only runs with `scheduledFor` strictly older than it
+ * are returned (cursor for paginating into history).
  */
-export function listHeartbeatRuns(limit = 20): HeartbeatRunRecord[] {
+export function listHeartbeatRuns(
+  limit = 20,
+  before?: number,
+): HeartbeatRunRecord[] {
   const db = getDb();
   const rows = db
     .select()
     .from(heartbeatRuns)
+    .where(before != null ? lt(heartbeatRuns.scheduledFor, before) : undefined)
     .orderBy(desc(heartbeatRuns.scheduledFor))
     .limit(limit)
     .all();

package/src/home/feed-types.ts

@@ -43,7 +43,7 @@ export {
 } from "../api/responses/home.js";
 
 /**
- * On-disk file format for `~/.vellum/workspace/data/home-feed.json`.
+ * On-disk file format for `$VELLUM_WORKSPACE_DIR/data/home-feed.json`.
  *
  * Written by the feed writer, read by the HTTP route and `parseFeedFile`
  * below. `version` is pinned to `2` (collapsed schema); pre-v2 files are

package/src/ipc/gateway-flag-listener.ts

@@ -3,11 +3,35 @@ import { connect, type Socket } from "node:net";
 import { refreshOverridesFromGateway } from "../config/assistant-feature-flags.js";
 import { SYNC_TAGS } from "../daemon/message-types/sync.js";
 import { publishSyncInvalidation } from "../runtime/sync/sync-publisher.js";
+import { syncFlagGatedTools } from "../tools/registry.js";
 import { getLogger } from "../util/logger.js";
 import { resolveIpcSocketPath } from "./socket-path.js";
 
 const log = getLogger("gateway-flag-listener");
 
+/**
+ * Refresh the flag-overrides cache from the gateway, then register any
+ * registry-gated tools whose flag gate has since opened. Both the
+ * `feature_flags_changed` event and a reconnect only refresh the cache;
+ * `syncFlagGatedTools` registers the CES tools whose flag is enabled so that
+ * enabling a CES-gating flag at runtime surfaces them without a daemon restart.
+ * Workflow tools (`run_workflow` / `manage_workflows`) are not registry-gated:
+ * they live in a flag-gated bundled skill surfaced via `skill_load` against the
+ * live flag cache, so they need no registry sync here. `syncFlagGatedTools` is
+ * idempotent and enable-only, so re-running it on every refresh is safe; it also
+ * never throws (it logs internally).
+ */
+function refreshFlagsAndSyncTools(context: string): void {
+  refreshOverridesFromGateway()
+    .then(() => syncFlagGatedTools())
+    .catch((err) => {
+      log.warn(
+        { err },
+        `Failed to refresh feature flag overrides (${context})`,
+      );
+    });
+}
+
 const MAX_BACKOFF_MS = 30_000;
 const INITIAL_BACKOFF_MS = 1_000;
 
@@ -29,9 +53,7 @@ function handleData(chunk: Buffer): void {
       const msg = JSON.parse(trimmed) as { event?: string };
       if (msg.event === "feature_flags_changed") {
         log.info("Received feature_flags_changed event — refreshing overrides");
-        refreshOverridesFromGateway().catch((err) => {
-          log.warn({ err }, "Failed to refresh feature flag overrides");
-        });
+        refreshFlagsAndSyncTools("flags-changed event");
         // Fan out to every connected web client so React Query caches
         // for `/v1/feature-flags/client-flag-values/` and
         // `/v1/assistants/:id/feature-flags` invalidate immediately
@@ -72,9 +94,9 @@ function connectToGateway(): void {
     log.info("Connected to gateway IPC for flag events");
     currentBackoffMs = INITIAL_BACKOFF_MS;
     socket = conn;
-    refreshOverridesFromGateway().catch((err) => {
-      log.warn({ err }, "Failed to refresh feature flag overrides on reconnect");
-    });
+    // A reconnect may have missed a flag flip while disconnected, so sync the
+    // gated tools too — not just the cache.
+    refreshFlagsAndSyncTools("reconnect");
   });
 
   let buffer = "";

package/src/mcp/mcp-auth-state.ts

@@ -96,38 +96,26 @@ export function setMcpAuthError(
 }
 
 /**
- * Get the current state of an OAuth flow, or null if none exists.
+ * Get the current state of an OAuth flow, or null if none exists. Sweeps
+ * expired entries on every read so a long-polling CLI can never observe
+ * a stale flow past its TTL.
  */
 export function getMcpAuthState(serverId: string): McpAuthState | null {
-  clearExpiredMcpAuthStates();
-  return activeMcpAuthFlows.get(serverId) ?? null;
-}
-
-/**
- * Remove expired entries from the auth flow map.
- */
-export function clearExpiredMcpAuthStates(): void {
   const now = Date.now();
-  for (const [serverId, state] of activeMcpAuthFlows) {
+  for (const [id, state] of activeMcpAuthFlows) {
     if (state.status === "pending" && now > state.expiresAt) {
-      activeMcpAuthFlows.delete(serverId);
+      activeMcpAuthFlows.delete(id);
     } else if (
       state.status === "complete" &&
       now > state.completedAt + COMPLETION_GRACE_MS
     ) {
-      activeMcpAuthFlows.delete(serverId);
+      activeMcpAuthFlows.delete(id);
     } else if (
       state.status === "error" &&
       now > state.failedAt + COMPLETION_GRACE_MS
     ) {
-      activeMcpAuthFlows.delete(serverId);
+      activeMcpAuthFlows.delete(id);
     }
   }
-}
-
-/**
- * Test-only helper — clears all auth flow state for test isolation.
- */
-export function _clearAllMcpAuthStates(): void {
-  activeMcpAuthFlows.clear();
+  return activeMcpAuthFlows.get(serverId) ?? null;
 }